Skip to content

Commit

Permalink
docs(swagger-builder): add missing option in readme documentation (#2012
Browse files Browse the repository at this point in the history 
)

## Proposed change

Add missing option in swagger-builder readme.md documentation

<!-- Please include a summary of the changes and the related issue.
Please also include relevant motivation and context. List any
dependencies that is required for this change. -->

## Related issues

- 🐛 Fixes #1994

<!-- Please make sure to follow the contributing guidelines on
https://github.com/amadeus-digital/Otter/blob/main/CONTRIBUTING.md -->
  • Loading branch information
@kpanot
kpanot authored Jul 31, 2024
2 parents 1e65e73 + 20a38b3 commit c2685f7
Showing 1 changed file with 25 additions and 22 deletions.
47 changes: 25 additions & 22 deletions docs/swagger-builder/readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ The **Swagger Builder** supports three formats of Swagger specification as input
The **Swagger Builder** tool will merge all the Swagger specifications entered as arguments (in any of the 3 formats chosen above) from the first entry to the last one as described in the [merging strategy](./merging-strategy.md).

>**Information**: The input support *Glob patterns* to list several files
## Configuration

The **Swagger Builder** supports two kinds of configuration:
Expand All @@ -58,39 +59,41 @@ The **Swagger Builder** supports a set of *configuration* to configure the mergi
The configurations can be specified in a JSON file following a provided [Json Schema](./packages/@ama-sdk/swagger-builder/src/schemas/builder-configuration.schema.json) or via CLI options.
> [!WARNING]
> The CLI Options will **be overridden by** the configuration provided in the JSON file.
### List of available configurations

| Configuration | CLI Option | Description | Default value |
|:------------------------|:---------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------|
| **outputFormat** | **--output-format** (alias: **-O**) | Type of artifact generated. The supported formats are [split](./split-swagger-spec.md), `yaml` and `json` | yaml |
| **output** | **--output** (alias: **-o**) | Path of the artifact generated.<br/> In case of `yaml` (or `json`) output format, the `.yaml` (or `.json`) extension will be added to the path.<br/> In the case of `split` output format, the output path will be the name of the folder containing the generated split spec. | ./result/spec |
| **setVersion** | **--set-version** (alias: **-v**) | Set the version of the final Swagger spec. If not specified, the most recent version of the specification (in input) will be used | *null* |
| **setVersionAuto** | **--set-version-auto** (alias: **-u**) | If enabled, the version from the current package.json will be applied to the final swagger specification. This option will be ignored if a manual version is specified in **setVersion** configuration. | *null* |
| **artifact** | **--artifact** (alias: **-a**) | Name of the NPM artifact associated to the Swagger specification generated. If specified, a `package.json` will be generated alongside the Swagger specification (in the same folder) | *null* |
| **ignoreConflict** | **--ignore-conflict** (alias: **-i**) | Ignore the conflict (in the **paths**) during the specification merging. If enabled, the previous conflicting *path* will be replaced by the new one (in the [Merging strategy](./merging-strategy.md)) | `false` |
| **awsCompat** | **--aws-compat** | Enable Amazon Web Service Gateway compatibility. The resulting Swagger specification will be transformed to be compatible with AWS | `false` |
| **treeShaking** | **--tree-shaking** | Enable the tree shaking of the Swagger output. The `definitions` and `parameters` not referred to by a `path` will be removed. This option is enabled per default in case of black/white listing | `false` |
| **treeShakingStrategy** | **--tree-shaking-strategy** | Change the tree shaking strategy. Options are `bottom-up` or `top-down`. | `bottom-up` |
| **validation** | **--no-validation** | Enable validation of the generated Swagger specification | `true` |
| **flagDefinition** | **--flag-definition** | Flag all definition with a vendor extension x-api-ref: {Definition name} | `false` |
| **buildMdkSpec** | **--build-mdk-spec** | Build the swagger spec to be MDK compliant | `false` |
| **pathsWhiteList** | | List of whitelisted paths to keep to the final Swagger specification. If specified, the `tree shaking` post process will be run to the Swagger specification | *null* |
| **pathsBlackList** | | List of blacklisted paths to remove from the final Swagger specification If specified, the `tree shaking` post process will be run to the Swagger specification | *null* |
| **specs** | *CLI Arguments* | List of Swagger specification to merge. If both **configuration** and **CLI arguments** are provided the specifications provided as *CLI arguments* will be merged **after** the one from the configuration file | [ ] |
| Configuration | CLI Option | Description | Default value |
| :------------------------------ | :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ |
| **outputFormat** | **--output-format** (alias: **-O**) | Type of artifact generated. The supported formats are [split](./split-swagger-spec.md), `yaml` and `json` | yaml |
| **output** | **--output** (alias: **-o**) | Path of the artifact generated.<br/> In case of `yaml` (or `json`) output format, the `.yaml` (or `.json`) extension will be added to the path.<br/> In the case of `split` output format, the output path will be the name of the folder containing the generated split spec. | ./result/spec |
| **setVersion** | **--set-version** (alias: **-v**) | Set the version of the final Swagger spec. If not specified, the most recent version of the specification (in input) will be used | *null* |
| **setVersionAuto** | **--set-version-auto** (alias: **-u**) | If enabled, the version from the current package.json will be applied to the final swagger specification. This option will be ignored if a manual version is specified in **setVersion** configuration. | *null* |
| **artifact** | **--artifact** (alias: **-a**) | Name of the NPM artifact associated to the Swagger specification generated. If specified, a `package.json` will be generated alongside the Swagger specification (in the same folder) | *null* |
| **ignoreConflict** | **--ignore-conflict** (alias: **-i**) | Ignore the conflict (in the **paths**) during the specification merging. If enabled, the previous conflicting *path* will be replaced by the new one (in the [Merging strategy](./merging-strategy.md)) | `false` |
| **awsCompat** | **--aws-compat** | Enable Amazon Web Service Gateway compatibility. The resulting Swagger specification will be transformed to be compatible with AWS | `false` |
| **treeShaking** | **--tree-shaking** | Enable the tree shaking of the Swagger output. The `definitions` and `parameters` not referred to by a `path` will be removed. This option is enabled per default in case of black/white listing | `false` |
| **treeShakingStrategy** | **--tree-shaking-strategy** | Change the tree shaking strategy. Options are `bottom-up` or `top-down`. | `bottom-up` |
| **validation** | **--no-validation** | Enable validation of the generated Swagger specification | `true` |
| **flagDefinition** | **--flag-definition** | Flag all definition with a vendor extension x-api-ref: {Definition name} | `false` |
| **buildMdkSpec** | **--build-mdk-spec** | Build the swagger spec to be MDK compliant | `false` |
| **pathsWhiteList** | | List of whitelisted paths to keep to the final Swagger specification. If specified, the `tree shaking` post process will be run to the Swagger specification | *null* |
| **pathsBlackList** | | List of blacklisted paths to remove from the final Swagger specification If specified, the `tree shaking` post process will be run to the Swagger specification | *null* |
| **flattenConflictedDefinition** | | Merge based interface with new override in case of definition name conflict | `false` |
| **specs** | *CLI Arguments* | List of Swagger specification to merge. If both **configuration** and **CLI arguments** are provided the specifications provided as *CLI arguments* will be merged **after** the one from the configuration file | [ ] |

### List of additional CLI Options

| Feature | CLI Option | Description | Default value |
| :---------------- | :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ |
| **Configuration** | **--configuration** (alias: **-c**) | [Configuration file](#list-of-available-configurations) to provide parameters to the **Swagger Builder** | *null* |
| Feature | CLI Option | Description | Default value |
| :---------------- | :---------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ |
| **Configuration** | **--configuration** (alias: **-c**) | [Configuration file](#list-of-available-configurations) to provide parameters to the **Swagger Builder** | *null* |
| **APIs** | **--apis** | Path to the files containing a [list of APIs](./multi-apis.md) to generate. Each APIs will be merged with the ones in the CLI argument (if specified). | *null* |

## Additional Checking tools

To perform validity check of a set of Swagger Specifications, additional tools are provided by the package:

| Name | Description |
| :----------------------------------------------------------------------- | :---------------------------------------------------------------------------------- |
| Name | Description |
| :------------------------------------------------------------------ | :---------------------------------------------------------------------------------- |
| [Dictionary check](./checkers/dictionary-checker.md) | Validate that the dictionaries linked via the X Vendors are valid |
| [Operation ID check](./checkers/operation-id-checker.md) | Validate that Operation IDs are specified and unique for each paths |
| [Multi Success Response check](./checkers/multi-success-checker.md) | Validate that there is no path returning two different success response definitions |
Expand Down

0 comments on commit c2685f7

Please sign in to comment.