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