github.com/go-swagger/go-swagger@v0.31.0/docs/reference/transform/_index.md (about)

     1  ---
     2  title: Spec transformations
     3  date: 2023-01-01T01:01:01-08:00
     4  draft: true
     5  ---
     6  # Transforming specifications
     7  
     8  The `swagger` toolkit allows some transformation to be carried out with a specification.
     9  
    10  Currently it is possible to apply the following transforms:
    11  - expansion: this expands all `$ref`'s in a spec
    12  - minimal flattening: carries on minimal transformation to a spec to be workable for the swagger codegen
    13  - full flattening: performs minimal flattening and in addition, replaces all complex constructs in schemas by named definitions
    14  - mixin: merges one or more specifications into a primary spec
    15  
    16  In addition, it is possible to compare specs (diff) to inspect breaking changes in the API.
    17  
    18  ### Expansion
    19  
    20  Expanding a spec may prove useful to validate a schema, produce documentation or test cases. The primary intent is not code generation.
    21  
    22  > **NOTE**: Circular `$ref` are detected and remain as local `$ref`. Remote circular `$ref` remain remote 
    23  > (favor `flatten` to regroup all remote `$ref` under one single root document).
    24  
    25  Usage:
    26  
    27  `swagger expand {spec}`
    28  or
    29  
    30  `swagger flatten --with-expand` {spec}`
    31  
    32  Full list of available options [for expand](../../usage/expand.md) and [for flatten](../../usage/flatten.md).
    33  
    34  or with codegen commands:
    35  
    36  `swagger generate [model|server|client|operation|...] --spec={spec} --with-expand`
    37  
    38  > **NOTE**: codegen may fail in some situations with spec expansion:
    39  > - polymorphism: the original intent of the `$ref` pointing to a discriminated type (i.e. _extends type..._) is lost with expansion
    40  > - duplicate names: expansion of `$ref` intended for type reuse may produce duplicate type identifiers
    41  > - too many generated files: expansion of large specs may lead to many independent anonymous structures
    42  
    43  ### Minimal flattening
    44  
    45  This transform makes complex JSON `$ref` amenable to analysis and code generation.
    46  
    47  Minimal flattening attempts to minimally distort the original specification intent, while ensuring workable codegen.
    48  
    49  Minimal flattening does:
    50  
    51  - bundle all external `$ref`s into the local document
    52  - resolve JSON pointers to anonymous places in the document (e.g. `"$ref": "#/definitions/thisModel/properties/codeName"`)
    53  - resolve `$ref`s in swagger-specific sections: `parameters` and `responses`, so the only remaining `$ref`s are located in schemas
    54  
    55  All `$ref`s in the resulting spec are thus only found in schema, with the _canonical_ form: `"$ref": "#/definitions/modelName"`.
    56  
    57  Usage:
    58  
    59  `swagger flatten {spec}`
    60  
    61  or more explicitly:
    62  
    63  `swagger flatten --with-flatten=minimal {spec}`
    64  
    65  This is the default option for codegen commands:
    66  
    67  `swagger generate [model|server|client|operation|...] --spec={spec}`
    68  
    69  > **NOTE**: `$ref` bundling / pointer resolving may in some cases produce duplicate names.
    70  > The flattener tries to resolve duplicates whenever possible (such as when a child identifier duplicates its parent).
    71  > When such resolution is not possible, an "OAIGen" suffix is added to the definition name (a warning is issued).
    72  > You may use the `x-go-name` extension here to set a more suitable name for the generated type.
    73  
    74  ### Full flattening
    75  
    76  Full flattening is useful to factorize data model objects into simpler structures.
    77  
    78  > Complex structures (i.e. objects with properties or schemas with an `allOf` composition) are moved to standalone definitions.
    79  > Arrays and map constructs (e.g. AdditionalProperties) are not considered complex.
    80  
    81  Usage:
    82  
    83  `swagger flatten --with-flatten=full {spec}`
    84  
    85  Or with codegen commands:
    86  
    87  `swagger generate [model|server|client|operation|...] --spec={spec} --with-flatten=full`
    88  
    89  > **NOTE**: this used to be the default for codegen commands with releases 0.13 and 0.14. 
    90  > This behavior has been reverted with release 0.15.
    91  
    92  You may not like the automatic names chosen for the new structures (e.g. `myModelAllOf3`, `myModelAdditionalPropertiesAdditionalProperties` ...).
    93  Again, the `x-go-name` extension is the way to generate custom names that are easier to use in your API code.
    94  
    95  Ex:
    96  ```yaml
    97  definitions:
    98    complexArray:
    99      schema:
   100        type: array
   101        items:
   102          type: object        # <- inline schema for items
   103          properties:
   104            prop1:
   105              type: integer
   106  ```
   107  
   108  Is factorized as:
   109  
   110  ```yaml
   111  definitions:
   112    complexArray:
   113      schema:
   114        type: array
   115        items:
   116          $ref: '#/definitions/complexArrayItems'
   117    complexArrayItems:
   118      type: object
   119      properties:
   120        prop1:
   121          type: integer
   122  ```
   123  
   124  ### Other flattening options
   125  
   126  The `--with-flatten` option supports the following additional arguments:
   127  
   128  - `verbose`, `noverbose`: allows/mute warnings about the transformation
   129  - `remove-unused`: removes unused definitions after expansion or flattening
   130  
   131  > **NOTE**: you may specify multiple options like this:
   132  >
   133  > `swagger flatten {spec} --with-flatten=remove-unused --with-flatten=full`
   134  
   135  ### Mixin
   136  
   137  Usage:
   138  
   139  `swagger mixin {primary spec} [{spec to merge}...]`
   140  
   141  Full list of available options [here](../../usage/mixin.md).
   142  
   143  ### Roadmap
   144  
   145  This set of features is essentially provided by the `github.com/go-openapi/analysis` package.
   146  Feel free to contribute new features to this repo.
   147  
   148  Currently, here is a todo list of improvements planned to the spec preprocessing feature:
   149  
   150  - in full flatten mode, more options to control how allOf are handled
   151  - in full flatten mode propagating `x-go-name` (as prefix) to newly created definitions. 
   152  As creating new definitions introduces some naming conventions.
   153  If a x-go-name has been set in the original structure, new names should remain consistent with their container...
   154  - struct name analysis and better prediction/resolution of duplicate identifiers