LukeParke/redocly-cli
1
0
Fork 0
mirror of https://github.com/LukeHagar/redocly-cli.git synced 2025-12-06 04:21:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Use Museum API instead of Petstore examples (#1386)

Browse Source 
* docs: add museum examples to installation and bundle/join commands

* docs: removed petstore examples and updated formatting for readability

* docs: Update petstore to museum examples in decorators section

* chore: Prettier wants to fix a file

* chore: Fix Vale-detected future tense mistakes

* Update docs/decorators/media-type-examples-override.md

* Update docs/commands/lint.md

* Update docs/commands/lint.md

---------

Co-authored-by: Heather Cloward <heathercloward@gmail.com>
This commit is contained in:
Lorna Jane Mitchell
2024-02-12 18:06:11 +00:00
committed by GitHub
parent 4a913d6690
commit fd79f7d4c5
5 changed files with 278 additions and 333 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
docs/commands/bundle.md
View File

@@ -62,12 +62,12 @@ redocly bundle openapi/openapi.yaml --output dist/openapi.json
This command creates one bundled file for each of the specified apis in the `dist/` folder. Bundled files are in JSON format. This command creates one bundled file for each of the specified apis in the `dist/` folder. Bundled files are in JSON format.
```bash Command ```bash Command
redocly bundle --output dist --ext json openapi/openapi.yaml openapi/petstore.yaml redocly bundle --output dist --ext json openapi/openapi.yaml openapi/museum.yaml
``` ```
```bash Output ```bash Output
dist/openapi.json dist/openapi.json
dist/petstore.json dist/museum.json
``` ```
### Create a fully dereferenced bundle ### Create a fully dereferenced bundle
@@ -75,7 +75,7 @@ dist/petstore.json
A fully dereferenced bundle does not use `$ref` at all, all the references are resolved and placed into the API description file. This can be useful if you need to prepare an OpenAPI file to be used by another tool that does not understand the `$ref` syntax. A fully dereferenced bundle does not use `$ref` at all, all the references are resolved and placed into the API description file. This can be useful if you need to prepare an OpenAPI file to be used by another tool that does not understand the `$ref` syntax.
```bash ```bash
redocly bundle --dereferenced --output dist --ext json openapi/openapi.yaml openapi/petstore.yaml redocly bundle --dereferenced --output dist --ext json openapi/openapi.yaml openapi/museum.yaml
``` ```
{% admonition type="warning" name="Note" %} {% admonition type="warning" name="Note" %}
@@ -90,98 +90,6 @@ By default, the CLI tool looks for the Redocly configuration file in the current
redocly bundle --config=./another/directory/config.yaml redocly bundle --config=./another/directory/config.yaml
``` ```
### Format
#### Codeframe (default)
```bash
redocly bundle pet.yaml store.yaml -o ./bundled --format=codeframe
## equivalent to: redocly bundle pet.yaml store.yaml -o ./bundled
```
Note: Errors display in the following format: `file:line:column`. For example, `petstore-with-errors.yaml:16:3`.
Depending on the terminal emulator you use, it may be possible to directly click this indicator to edit the file in place.
#### Stylish
```bash
redocly bundle pet.yaml store.yaml -o ./bundled --format=stylish
```
In this format, `bundle` shows the filename, line number, and column where the problem occurred.
The compressed output omits other contexts and suggestions.
#### JSON
{% tabs %}
{% tab label="Command" %}
```bash
redocly bundle pet.yaml store.yaml -o ./bundled --format=json
```
{% /tab %}
{% tab label="Output" %}
```bash
bundling pet.yaml...
{
"totals": {
"errors": 0,
"warnings": 0,
"ignored": 0
},
"version": "1.0.0-beta.54",
"problems": []
}📦 Created a bundle for pet.yaml at bundled/pet.yaml 28ms.
bundling store.yaml...
{
"totals": {
"errors": 0,
"warnings": 0,
"ignored": 0
},
"version": "1.0.0-beta.54",
"problems": []
}📦 Created a bundle for store.yaml at bundled/store.yaml 15ms.
```
{% /tab %}
{% /tabs %}
In this format, `bundle` shows the result of bundling (including the number of errors and warnings and their descriptions) in JSON-like output.
#### Checkstyle
{% tabs %}
{% tab label="Command" %}
```bash
redocly bundle pet.yaml -o ./bundled --lint --format=checkstyle
```
{% /tab %}
{% tab label="Output" %}
```bash
bundling pet.yaml...
<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="4.3">
<file name="pet.yaml">
</file>
</checkstyle>
📦 Created a bundle for pet.yaml at bundled/pet.yaml 35ms.
```
{% /tab %}
{% /tabs %}
In this format, `bundle` uses the [Checkstyle](https://checkstyle.org/) XML report format.
Due to the limitations of this format, the output _only_ includes the filename, line, column, severity,
and rule ID (in the `source` attribute).
All other information is omitted.
### Skip preprocessor, rule, or decorator ### Skip preprocessor, rule, or decorator
You may want to skip specific preprocessors, rules, or decorators upon running the command. You may want to skip specific preprocessors, rules, or decorators upon running the command.

103
docs/commands/join.md
View File

@@ -105,7 +105,7 @@ x-tagGroups:
description: 'Text from info: description of the first input file' description: 'Text from info: description of the first input file'
- name: second-api - name: second-api
tags: tags:
- pets - partner
description: 'Text from info: description of the second input file' description: 'Text from info: description of the second input file'
``` ```
@@ -123,17 +123,17 @@ Path names and component names must be unique in all input files, but their cont
If the `join` command detects any conflicting content while trying to combine the input files, it displays informative messages about the conflicts and exits without creating an output file. To prevent this, use optional parameters to add prefixes to tags and components. If the `join` command detects any conflicting content while trying to combine the input files, it displays informative messages about the conflicts and exits without creating an output file. To prevent this, use optional parameters to add prefixes to tags and components.
```bash ```bash
Conflict on tags => all : pets in files: petstore.yaml,test.yaml Conflict on tags => all : tickets in files: museum.yaml,exhibition.yaml
1 conflict(s) on tags. 1 conflict(s) on tags.
Suggestion: please use prefix-tags-with-filename, prefix-tags-with-info-prop or without-x-tag-groups to prevent naming conflicts. Suggestion: please use prefix-tags-with-filename, prefix-tags-with-info-prop or without-x-tag-groups to prevent naming conflicts.
Conflict on paths => /pets : get in files: petstore.yaml,test.yaml Conflict on paths => /tickets : get in files: museum.yaml,exhibition.yaml
Conflict on paths => /pets : post in files: petstore.yaml,test.yaml Conflict on paths => /tickets : post in files: museum.yaml,exhibition.yaml
Conflict on paths => operationIds : listPets in files: petstore.yaml,test.yaml Conflict on paths => operationIds : listEvents in files: museum.yaml,exhibition.yaml
Conflict on paths => operationIds : createPets in files: petstore.yaml,test.yaml Conflict on paths => operationIds : createEvent in files: museum.yaml,exhibition.yaml
Conflict on paths => operationIds : showPetById in files: petstore.yaml,test.yaml Conflict on paths => operationIds : getEvent in files: museum.yaml,exhibition.yaml
Conflict on paths => /pets/{petId} : get in files: petstore.yaml,test.yaml Conflict on paths => /tickets/{Id} : get in files: museum.yaml,exhibition.yaml
Please fix conflicts before running join. Please fix conflicts before running join.
``` ```
@@ -167,9 +167,9 @@ redocly join first-api.yaml second-api.json --prefix-tags-with-info-prop title
description: endpoints tag description description: endpoints tag description
x-displayName: endpoints x-displayName: endpoints
- name: Second document title_pets - name: Second document title_events
description: pets tag description description: events tag description
x-displayName: pets x-displayName: events
``` ```
{% /tab %} {% /tab %}
@@ -198,9 +198,9 @@ redocly join first-api.yaml second-api.json --prefix-tags-with-filename true
description: endpoints tag description description: endpoints tag description
x-displayName: endpoints x-displayName: endpoints
- name: second-api_pets - name: second-api_events
description: pets tag description description: events tag description
x-displayName: pets x-displayName: events
``` ```
{% /tab %} {% /tab %}
@@ -230,11 +230,8 @@ If any of the input files have conflicting component names, this option can be u
#### Usage #### Usage
{% tabs %}
{% tab label="Command" %}
```bash ```bash
redocly join first-api.yaml second-api.json --prefix-components-with-info-prop version redocly join museum_v1.yaml museum_v2.json --prefix-components-with-info-prop version
``` ```
{% /tab %} {% /tab %}
@@ -243,35 +240,51 @@ redocly join first-api.yaml second-api.json --prefix-components-with-info-prop v
```yaml ```yaml
components: components:
schemas: schemas:
1.0.1_Pet: 1.0.0_BuyMuseumTicketsRequest:
allOf: description: Request payload used for purchasing museum tickets.
- $ref: '#/components/schemas/NewPet'
- type: object
required:
- id
properties:
id:
type: integer
format: int64
1.0.1_NewPet:
type: object type: object
required:
- name
properties: properties:
name: ticketType:
type: string $ref: '#/components/schemas/1.0.0_TicketType'
tag: eventId:
type: string description: >-
1.2.0_Pet: Unique identifier for a special event. Required if purchasing
allOf: tickets for the museum's special events.
- $ref: '#/components/schemas/NewPet' $ref: '#/components/schemas/1.0.0_1.0.0_EventId'
- type: object ticketDate:
required: description: Date that the ticket is valid for.
- id $ref: '#/components/schemas/1.0.0_1.0.0_Date'
properties: email:
id: $ref: '#/components/schemas/1.0.0_Email'
type: integer phone:
format: int64 $ref: '#/components/schemas/1.0.0_Phone'
required:
- ticketType
- ticketDate
- email
1.2.0_BuyMuseumTicketsRequest:
description: Request payload used for purchasing museum tickets.
type: object
properties:
ticketType:
$ref: '#/components/schemas/1.2.0_TicketType'
eventId:
description: >-
Unique identifier for a special event. Required if purchasing
tickets for the museum's special events.
$ref: '#/components/schemas/1.2.0_1.2.0_EventId'
ticketDate:
description: Date that the ticket is valid for.
$ref: '#/components/schemas/1.2.0_1.2.0_Date'
email:
$ref: '#/components/schemas/1.2.0_Email'
phone:
$ref: '#/components/schemas/1.2.0_Phone'
required:
- ticketType
- ticketDate
- email
``` ```
{% /tab %} {% /tab %}

224
docs/commands/lint.md
View File

@@ -44,9 +44,7 @@ The `lint` command behaves differently depending on how you pass apis to it and
#### Pass an API directly #### Pass an API directly
```bash `redocly lint openapi/openapi.yaml`
redocly lint openapi/openapi.yaml
```
In this case, `lint` validates the API description(s) passed to the command. If you have no configuration file defined, the [recommended ruleset](../rules/recommended.md) is used. If you have `extends` or `rules` defined in `redocly.yaml`, those are used when linting. In this case, `lint` validates the API description(s) passed to the command. If you have no configuration file defined, the [recommended ruleset](../rules/recommended.md) is used. If you have `extends` or `rules` defined in `redocly.yaml`, those are used when linting.
@@ -54,16 +52,7 @@ The `apis` argument can also use any glob format supported by your file system.
#### An API from the configuration file #### An API from the configuration file
Instead of full paths, you can use names listed in the `apis` section of your Redocly configuration file. Instead of full paths, you can use names listed in the `apis` section of your Redocly configuration file. The example `redocly.yaml` file below shows an API alias `core@v1` defined:
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint core@v1
```
{% /tab %}
{% tab label="Configuration file" %}
```yaml ```yaml
apis: apis:
@@ -71,23 +60,15 @@ apis:
root: ./openapi/api-description.json root: ./openapi/api-description.json
``` ```
{% /tab %} Use the alias with the lint command as shown:
{% /tabs %}
`redocly lint core@v1`
In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `lint` validates the `api-description.json` file. The presence of the Redocly configuration file is mandatory. In this case, after resolving the path behind the `core@v1` name (see the `Configuration file` tab), `lint` validates the `api-description.json` file. The presence of the Redocly configuration file is mandatory.
#### All configured APIs #### All configured APIs
You can omit apis completely when executing the `lint` command to check all APIs defined in the configuration file. You can omit apis completely when executing the `lint` command to check all APIs defined in the configuration file. Run `redocly lint` with no arguments to lint all defined APIs; an example `redocly.yaml` file is shown below:
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint
```
{% /tab %}
{% tab label="Configuration file" %}
```yaml ```yaml
apis: apis:
@@ -99,10 +80,6 @@ apis:
root: ./openapi/sandbox.yaml root: ./openapi/sandbox.yaml
``` ```
{% /tab %}
{% /tabs %}
In this case, if no API descriptions are specified, `lint` validates all apis listed under `apis` in your Redocly configuration file. The presence of the configuration file is mandatory.
{% admonition type="warning" name="Important" %} {% admonition type="warning" name="Important" %}
If you try to execute the `lint` command without apis when your project doesn't have any configuration files, the `lint` command displays an error. If you try to execute the `lint` command without apis when your project doesn't have any configuration files, the `lint` command displays an error.
{% /admonition %} {% /admonition %}
@@ -111,9 +88,7 @@ If you try to execute the `lint` command without apis when your project doesn't
By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.md) in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file. By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.md) in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.
```bash `redocly lint --config=./another/directory/config.yaml`
redocly lint --config=./another/directory/config.yaml
```
### Extend configuration ### Extend configuration
@@ -134,94 +109,82 @@ Some formats, such as CheckStyle or JSON, don't work well when mulitple APIs are
#### Codeframe (default) #### Codeframe (default)
{% tabs %} The command `redocly lint --format=codeframe` lints the file and uses the default format of `codeframe`. You will see the same output as below if you omit the `--format` parameter.
{% tab label="Command" %}
```bash ```bash
redocly lint --format=codeframe [1] museum-with-errors.yaml:19:7 at #/paths/~1museum-hours/get/operationIds
## equivalent to: redocly lint
Property `operationIds` is not expected here.
Did you mean: operationId ?
17 | summary: Get museum hours
18 | description: Get upcoming museum operating hours
19 | operationIds: getMuseumHours
20 | tags:
21 | - Operations
Error was generated by the spec rule.
``` ```
{% /tab %} Note that the problems are displayed in the following format: `file:line:column`. For example, `museum-with-errors.yaml:19:7`.
{% tab label="Output" %}
```bash
[1] resources/petstore-with-errors.yaml:16:3 at #/paths/~1pets?id
Don't put query string items in the path, they belong in parameters with `in: query`.
14 | - name: pets
15 | paths:
16 | /pets?id:
| ^^^^^^^^
17 | get:
18 | summary: List all pets
Error was generated by the path-not-include-query rule.
```
{% /tab %}
{% /tabs %}
Note that the problems are displayed in the following format: `file:line:column`. For example, `petstore-with-errors.yaml:16:3`.
Depending on the terminal emulator you use, it may be possible to directly click this indicator to edit the file in place. Depending on the terminal emulator you use, it may be possible to directly click this indicator to edit the file in place.
#### Stylish #### Stylish
{% tabs %} The command `redocly lint --format=stylish` gives a more condensed output that is useful for summarizing the linting results, as seen below:
{% tab label="Command" %}
```bash ```bash
redocly lint --format=stylish museum-with-errors.yaml:
19:7 error spec Property `operationIds` is not expected here.
29:11 error spec Property `require` is not expected here.
16:5 warning operation-operationId Operation object should contain `operationId` field.
``` ```
{% /tab %}
{% tab label="Output" %}
```bash
openapi/core.yaml:
15:7 error spec Property `operationIds` is not expected here.
22:11 error spec Property `require` is not expected here.
14:7 warning operation-operationId Operation object should contain `operationId` field.
```
{% /tab %}
{% /tabs %}
In this format, `lint` shows the file name, line number, and column where the problem occurred. However, the output is compressed and omits other contexts and suggestions. In this format, `lint` shows the file name, line number, and column where the problem occurred. However, the output is compressed and omits other contexts and suggestions.
##### JSON ##### JSON
It can be useful to get the output in JSON format to be processed by other tools. It can be useful to get the output in JSON format to be processed by other tools. Use a command like `redocly lint --format=json` to get the following output:
{% tabs %}
{% tab label="Command" %}
```bash
redocly lint --format=json
```
{% /tab %}
{% tab label="Output" %}
```bash ```bash
{ {
"totals": { "totals": {
"errors": 1, "errors": 2,
"warnings": 1, "warnings": 1,
"ignored": 0 "ignored": 0
}, },
"version": "1.0.0-beta.84", "version": "1.7.0",
"problems": [ "problems": [
{ {
"ruleId": "spec", "ruleId": "spec",
"severity": "error", "severity": "error",
"message": "Property `operationIdentifier` is not expected here.", "message": "Property `operationIds` is not expected here.",
"suggest": [
"operationId"
],
"location": [
{
"source": {
"ref": "museum-with-errors.yaml"
},
"pointer": "#/paths/~1museum-hours/get/operationIds",
"reportOnKey": true
}
]
},
{
"ruleId": "spec",
"severity": "error",
"message": "Property `require` is not expected here.",
"suggest": [], "suggest": [],
"location": [ "location": [
{ {
"source": { "source": {
"ref": "myapi.yaml" "ref": "museum-with-errors.yaml"
}, },
"pointer": "#/paths/~1pathItem/post/operationIdentifier", "pointer": "#/paths/~1museum-hours/get/responses/200/require",
"reportOnKey": true "reportOnKey": true
} }
] ]
@@ -233,9 +196,9 @@ redocly lint --format=json
"location": [ "location": [
{ {
"source": { "source": {
"ref": "myapi.yaml" "ref": "museum-with-errors.yaml"
}, },
"pointer": "#/paths/~1pathItem/post/operationId", "pointer": "#/paths/~1museum-hours/get/operationId",
"reportOnKey": true "reportOnKey": true
} }
], ],
@@ -245,35 +208,22 @@ redocly lint --format=json
} }
``` ```
{% /tab %}
{% /tabs %}
#### Checkstyle #### Checkstyle
The `lint` command also supports the [Checkstyle](https://checkstyle.org/) XML report format. The `lint` command also supports the [Checkstyle](https://checkstyle.org/) XML report format
{% tabs %} Use a command like `redocly lint --format=checkstyle` to get this standard format output to use with your other tools.
{% tab label="Command" %}
```bash
redocly lint --format=checkstyle
```
{% /tab %}
{% tab label="Output" %}
```bash ```bash
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="4.3"> <checkstyle version="4.3">
<file name="openapi/core.yaml"> <file name="museum-with-errors.yaml">
<error line="15" column="7" severity="error" message="Property `operationIds` is not expected here." source="spec" /> <error line="19" column="7" severity="error" message="Property `operationIds` is not expected here." source="spec" />
<error line="22" column="11" severity="error" message="Property `require` is not expected here." source="spec" /> <error line="29" column="11" severity="error" message="Property `require` is not expected here." source="spec" />
<error line="14" column="7" severity="warning" message="Operation object should contain `operationId` field." source="operation-operationId" /> <error line="16" column="5" severity="warning" message="Operation object should contain `operationId` field." source="operation-operationId" />
</file> </file>
</checkstyle> </checkstyle>
``` ```
{% /tab %}
{% /tabs %}
Due to the limitations of this format, only file name, line, column, severity, Due to the limitations of this format, only file name, line, column, severity,
and rule ID (in the `source` attribute) are included. All other information is and rule ID (in the `source` attribute) are included. All other information is
omitted. omitted.
@@ -281,46 +231,26 @@ omitted.
### <a id="max-problems"></a>Limit the problem count ### <a id="max-problems"></a>Limit the problem count
With the `--max-problems` option, you can limit the number of problems displayed in the command output. If the number of detected problems exceeds the specified threshold, the remaining problems are hidden under the "spoiler message" that lets you know how many problems were hidden. With the `--max-problems` option, you can limit the number of problems displayed in the command output. If the number of detected problems exceeds the specified threshold, the remaining problems are hidden under the "spoiler message" that lets you know how many problems were hidden.
{% tabs %}
{% tab label="Command" %}
```bash ```bash
redocly lint --max-problems 200
```
{% /tab %}
{% tab label="Output" %}
```bash
...
< ... 2 more problems hidden > increase with `--max-problems N` < ... 2 more problems hidden > increase with `--max-problems N`
``` ```
{% /tab %} The default value is 100.
{% /tabs %}
### Generate ignore file ### Generate ignore file
With this option, you can generate the `.redocly.lint-ignore.yaml` file to suppress error and warning severity problems in the output. You still receive visual feedback to let you know how many problems were ignored. With this option, you can generate the `.redocly.lint-ignore.yaml` file to suppress error and warning severity problems in the output. You still receive visual feedback to let you know how many problems were ignored.
This option is useful when you have an API design standard, but have some exceptions to the rule (for example, a legacy API operation). It allows for highly granular control. This option is useful when you have an API design standard, but have some exceptions to the rule (for example, a legacy API operation). It allows for highly granular control.
{% tabs %}
{% tab label="Command" %}
```shell `redocly lint museum-with-errors.yaml --generate-ignore-file` runs the lint command and adds all the errors to an ignore file.
redocly lint openapi/petstore.yaml --generate-ignore-file
```
{% /tab %}
{% tab label="Output" %}
```bash ```bash
...
Generated ignore file with 3 problems. Generated ignore file with 3 problems.
``` ```
{% /tab %} The errors in the ignore file `.redocly.lint-ignore.yaml` are ignored when the `lint` command is run.
{% /tabs %}
{% admonition type="warning" %} {% admonition type="warning" %}
This command overwrites an existing ignore file. This command overwrites an existing ignore file.
@@ -328,44 +258,30 @@ This command overwrites an existing ignore file.
To generate an ignore file for multiple API descriptions, pass them as arguments: To generate an ignore file for multiple API descriptions, pass them as arguments:
```bash `redocly lint v1.yaml v2.yaml --generate-ignore-file`
redocly lint v1.yaml v2.yaml --generate-ignore-file
```
Example of an ignore file: Example of an ignore file:
```yaml .redocly.lint-ignore.yaml file ```yaml .redocly.lint-ignore.yaml file
# This file instructs Redocly's linter to ignore the rules contained for specific parts of your API. # This file instructs Redocly's linter to ignore the rules contained for specific parts of your API.
# See https://redocly.com/docs/cli/ for more information. # See https://redoc.ly/docs/cli/ for more information.
openapi/petstore: museum-with-errors.yaml:
spec: spec:
- '#/paths/~1store/get/operationIds' - '#/paths/~1museum-hours/get/operationIds'
- '#/paths/~1store/get/parameters/0/require' - '#/paths/~1museum-hours/get/responses/200/require'
operation-operationId: operation-operationId:
- '#/paths/~1store/get' - '#/paths/~1museum-hours/get/operationId'
``` ```
The rule in the example is named `spec`, which indicates compliance with the OpenAPI spec. You can also manually add problems that should be ignored to specific rules. The rule in the example is named `spec`, which indicates compliance with the OpenAPI spec. You can also manually add problems that should be ignored to specific rules.
### Skip preprocessor or rule ### Skip preprocessor or rule
You may want to skip specific preprocessors or rules upon running the command. You may want to skip specific preprocessors or rules upon running the command. Examples for each option are as follows:
{% tabs %}
{% tab label="Skip preprocessors" %}
```bash - `redocly lint --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example`
redocly lint --skip-preprocessor=discriminator-mapping-to-one-of --skip-preprocessor=another-example
```
{% /tab %} - `redocly lint --skip-rule=no-sibling-refs --skip-rule=no-parent-tags`
{% tab label="Skip rules" %}
```bash
redocly lint --skip-rule=no-sibling-refs --skip-rule=no-parent-tags
```
{% /tab %}
{% /tabs %}
{% admonition type="success" name="Tip" %} {% admonition type="success" name="Tip" %}
To learn more about preprocessors, rules, and decorators, refer to the [custom plugins](../custom-plugins/index.md) page. To learn more about preprocessors, rules, and decorators, refer to the [custom plugins](../custom-plugins/index.md) page.

181
docs/decorators/media-type-examples-override.md
View File

@@ -1,12 +1,13 @@
# media-type-examples-override # media-type-examples-override
Replaces the examples in the corresponding file. Replaces the request body or response examples in an API description with the contents of a specified file.
## API design principles ## API design principles
Sometimes developers generate OpenAPI and the examples need to be added or improved after the fact. Sometimes developers generate OpenAPI and the examples need to be added or improved after the fact.
This generally happens when you have no permission to edit the source. This generally happens when you have no permission to edit the source.
This decorator provides a way to "overlay" a new examples over the source so that as the source changes, the modifications can be reapplied. This decorator provides a way to "overlay" new examples over an API description so that as the API changes, the modifications can be reapplied.
It replaces the whole `examples` section of the given media type for the request body or response status.
## Configuration ## Configuration
@@ -14,96 +15,202 @@ This decorator provides a way to "overlay" a new examples over the source so tha
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| operationIds | object | **REQUIRED.** Object consisting of operationIds as keys, and object as a value that containing the request and responses keys and example`s paths as values. | | operationIds | object | **REQUIRED.** Object consisting of operationIds as keys, and object as a value that containing the request and responses keys and example`s paths as values. |
Example of a configuration: An example of a configuration file using the `media-type-examples-override` decorator is shown below:
```yaml ```yaml
decorators: decorators:
media-type-examples-override: media-type-examples-override:
operationIds: operationIds:
PostPets: updateSpecialEvent:
request: request:
application/json: ./pet-examples.yaml application/json: ./private-event-examples.yaml
getMuseumHours:
responses: responses:
'200': '200':
application/json: ./pet-examples.yaml application/json: ./opening-hours-examples.yaml
'400':
application/json: ./pet-errors-examples.yaml
``` ```
Replace a `requestBody` media type example by using the `request` key in `redocly.yaml`.
The `examples` section in the API description is wholly replaced by the contents of the file you reference.
Replace a response media type example for a specific status by setting `responses` and then the desired status in your configuration file.
The `examples` section for that response status is replaced by the contents of the file specified.
**Note:** Only the `examples` field is replaced; the response status must already exist and be defined in the API description.
## Examples ## Examples
Given this API description with example: Given this API description with example:
```yaml ```yaml
openapi: 3.0.0 openapi: 3.1.0
info: info:
version: 1.0.0 title: Redocly Museum API
title: Swagger Petstore description: An imaginary, but delightful Museum API for interacting with museum services and information. Built with love by Redocly.
contact:
url: 'https://redocly.com/docs/cli/'
servers:
- url: 'https://api.fake-museum-example.com/v1'
paths: paths:
'/GETUser/{userId}': /museum-hours:
summary: getPet
get: get:
operationId: getUserByName summary: Get museum hours
operationId: getMuseumHours
responses: responses:
200: '200':
description: okay description: Success
content: content:
application/json: application/json:
schema:
$ref: '#/components/schemas/GetMuseumHoursResponse'
examples: examples:
pet: default_example:
value: $ref: '#/components/examples/GetMuseumHoursResponseExample'
name: test name '400':
description: Bad request
'404':
description: Not found
components:
schemas:
GetMuseumHoursResponse:
description: List of museum operating hours for consecutive days.
type: array
items:
$ref: '#/components/schemas/MuseumDailyHours'
MuseumDailyHours:
description: Daily operating hours for the museum.
type: object
properties:
date:
type: string
description: Date the operating hours apply to.
example: 2023-12-31
timeOpen:
type: string
description: Time the museum opens on a specific date. Uses 24 hour time format (`HH:mm`).
example: 09:00
timeClose:
description: Time the museum closes on a specific date. Uses 24 hour time format (`HH:mm`).
type: string
example: 18:00
GetMuseumHoursResponseExample:
summary: Get hours response
value:
- date: "2024-06-18"
timeOpen: "09:00"
timeClose: "18:00"
- date: "2024-06-19"
timeOpen: "09:00"
timeClose: "18:00"
``` ```
Given the file `./pet-examples.yaml` with content: Given the file `./opening-hours-examples.yaml` with content:
```yaml ```yaml
Cat: GetMuseumHoursResponseExampleShort:
summary: Short-term opening hours
value: value:
name: example - date: "2023-09-11"
timeOpen: "09:00"
timeClose: "18:00"
- date: "2023-09-12"
timeOpen: "09:00"
timeClose: "18:00"
GetMuseumHoursResponseExampleClosed:
summary: The museum is closed
value: []
``` ```
Given this configuration: Given this configuration:
```yaml ```yaml
decorators: decorators:
remove-unused-components: on
media-type-examples-override: media-type-examples-override:
operationIds: operationIds:
PostPets: getMuseumHours:
responses: responses:
'200': ./pet-examples.yaml '200':
application/json: ./opening-hours-examples.yaml
``` ```
The result of the bundle command {% admonition type="success" name="Tip" %}
By using the `remove-unused-components` decorator here, the bundle also removes the overwritten example from the components section of the API description.
{% /admonition %}
The result of the bundle command `redocly bundle openapi.yaml`:
```yaml ```yaml
openapi: 3.0.0 openapi: 3.1.0
info: info:
version: 1.0.0 title: Redocly Museum API
title: Swagger Petstore description: An imaginary, but delightful Museum API for interacting with museum services and information. Built with love by Redocly.
contact:
url: https://redocly.com/docs/cli/
servers:
- url: https://api.fake-museum-example.com/v1
paths: paths:
'/GETUser/{userId}': /museum-hours:
summary: getPet
get: get:
operationId: getUserByName summary: Get museum hours
operationId: getMuseumHours
responses: responses:
200: '200':
description: okay description: Success
content: content:
application/json: application/json:
schema:
$ref: '#/components/schemas/GetMuseumHoursResponse'
examples: examples:
Cat: GetMuseumHoursResponseExampleShort:
summary: Short-term opening hours
value: value:
name: example - date: '2023-09-11'
timeOpen: '09:00'
timeClose: '18:00'
- date: '2023-09-12'
timeOpen: '09:00'
timeClose: '18:00'
GetMuseumHoursResponseExampleClosed:
summary: The museum is closed
value: []
'400':
description: Bad request
'404':
description: Not found
components:
schemas:
GetMuseumHoursResponse:
description: List of museum operating hours for consecutive days.
type: array
items:
$ref: '#/components/schemas/MuseumDailyHours'
MuseumDailyHours:
description: Daily operating hours for the museum.
type: object
properties:
date:
type: string
description: Date the operating hours apply to.
example: '2023-12-31'
timeOpen:
type: string
description: Time the museum opens on a specific date. Uses 24 hour time format (`HH:mm`).
example: '09:00'
timeClose:
description: Time the museum closes on a specific date. Uses 24 hour time format (`HH:mm`).
type: string
example: '18:00'
``` ```
Use the `media-type-examples-override` decorator to maintain rich example sets in separate YAML or JSON files, and add them to your API description to give more complete or informative examples to your users.
## Related decorators ## Related decorators
- [operation-description-override](./operation-description-override.md) - [operation-description-override](./operation-description-override.md)
- [tag-description-override](./tag-description-override.md) - [tag-description-override](./tag-description-override.md)
- [tag-description-override](./tag-description-override.md) - [remove-unused-components](./remove-unused-components.md)
## Resources ## Resources
- [Decorator source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/decorators/common/info-description-override.ts) - [Decorator source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/decorators/common/info-description-override.ts)
- [Blog post about Overlays](../../../blog/openapi-overlays.md)

5
docs/installation.md
View File

@@ -45,7 +45,7 @@ npx @redocly/cli <command> [options]
{% tab label="Example with lint command" %} {% tab label="Example with lint command" %}
```shell ```shell
npx @redocly/cli@latest lint petstore.yaml npx @redocly/cli@latest lint openapi.yaml
``` ```
{% /tab %} {% /tab %}
@@ -75,10 +75,11 @@ docker pull ghcr.io/redocly/cli
To give a Docker container access to your OpenAPI description files, you need to mount the containing directory as a volume. Assuming the API description is in the current working directory, the command to use is: To give a Docker container access to your OpenAPI description files, you need to mount the containing directory as a volume. Assuming the API description is in the current working directory, the command to use is:
```shell Example with lint command ```shell Example with lint command
docker run --rm -v $PWD:/spec redocly/cli lint petstore.yaml docker run --rm -v $PWD:/spec redocly/cli lint openapi.yaml
``` ```
## Next steps ## Next steps
- Set up [autocomplete for Redocly CLI](./guides/autocomplete.md). - Set up [autocomplete for Redocly CLI](./guides/autocomplete.md).
- Check the full list of [Redocly CLI commands](./commands/index.md) available. - Check the full list of [Redocly CLI commands](./commands/index.md) available.
- Try things out with the [Museum Example API](https://github.com/Redocly/museum-openapi-example).