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