github.com/josephspurrier/go-swagger@v0.2.1-0.20221129144919-1f672a142a00/docs/use/transform.md (about)

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