909fb471ca
* feat: Add Vale configuration and rules * docs: Fix top-level files to match Vale rules * docs: Vale updates for the commands docs * docs: apply Vale updates to the decorator docs * docs: Update guides to match Vale rules * docs: update rules and other content to meet Vale standards * docs: add Vale link and information to CONTRIBUTING * feat: Add GitHub action for Vale * docs: minor editing to readme.md * docs: minor editing to the changelog.md file * docs: minor edits to the join.md file in commands folder * docs: minor edits to lint.md file in the commands directory * docs: minor edit to the login.md file in the commands directory * docs: minor edits to the preview.md file in the commands directory * docs: minor edits to push.md file in the comands directory * docs: minor edits to the info-description-override.md file in the decorators directory * docs: minor edits to the configure-rules.md file in the guides directory * docs: minor edits to custom-plugin.md file in the resources directory * docs: minor editing to the no-http-verbs-in-paths.md file in the rules directory --------- Co-authored-by: Heather Cloward <heathercloward@gmail.com>
8.8 KiB
tocMaxDepth, redirectFrom
| tocMaxDepth | redirectFrom | |
|---|---|---|
| 3 |
|
Enforce response contents with the response-contains-property rule
Overview
This guide describes how to ensure that the API operation's response contains a specific property with three different cases:
- Single response containing one property
- Multiple responses containing one property
- Multiple responses containing multiple properties
Let's get started!
Before you begin
- Use the openapi-starter repository to set up a basic project for use with this guide.
- Download the modified project files and use them to
replace the corresponding files in the
openapifolder:
.
└── openapi
├── components
│ └── responses
│ ├── 200.yaml
│ ├── 201.yaml
│ └── 202.yaml
└── paths
├── path-item-with-examples.yaml
├── path-item.yaml
└── users_{username}.yaml
:::note
Make sure that the @redocly/cli has version 1.0.0-beta.99 or later
:::
- If you're using VS Code as your favorite code editor, we recommend you install the Redocly OpenAPI VS Code extension.
:::note We do, You do This guide is most effective when you follow along and complete the steps. :::
Case 0 - Check that the current OpenAPI definition is valid
After downloading the openapi-starter repository, ensure that you installed the project's dependencies via npm install.
Once completed, in the project folder, execute the npx redocly lint command. You should receive confirmation that the OpenAPI definition is valid:
npx redocly lint
validating /openapi/openapi.yaml...
/openapi/openapi.yaml: validated in 39ms
Woohoo! Your OpenAPI definition is valid. 🎉
Now you are ready to configure the rules.
Case 1 - Single response containing one property
Imagine that your API definition describes users' data, and it should have user_id as a part of
all successful (200) responses. Let's define this.
- Open the
.redocly.yamlin the project folder - After the line 9, add the rule configuration block:
rules:
no-unused-components: error
response-contains-property:
severity: error
names:
200:
- user_id
npx redocly lint
validating /openapi/openapi.yaml...
[1] openapi/components/responses/200.yaml:2:1 at #/properties
Response object must contain a top-level "user_id" property.
...
Error was generated by the response-contains-property rule.
[2] openapi/components/responses/200.yaml:2:1 at #/properties
Response object must contain a top-level "user_id" property.
...
Error was generated by the response-contains-property rule.
[3] openapi/components/responses/200.yaml:2:1 at #/properties
Response object must contain a top-level "user_id" property.
...
Error was generated by the response-contains-property rule.
/openapi/openapi.yaml: validated in 51ms
❌ Validation failed with 3 errors.
run `openapi lint --generate-ignore-file` to add all problems to the ignore file.
If you're using the Redocly OpenAPI extension for VS Code, this is how the lint errors look in the integrated terminal (Problems tab):
What does the lint output mean
As you can see from the output, the rule triggered an error in the 200.yaml file
indicating there is no user_id property for 200 responses.
Three "copies" of the error mean that there are three $refs within the OpenAPI definition
that refer to the 200 response schema object.
Case 2 - Multiple responses containing one property
When you want to check that your OpenAPI definition contains property in all responses of a specific class, you can use ranges.
Let's modify the previous example to check that all 2xx responses contain the user_id property.
rules:
no-unused-components: error
response-contains-property:
severity: error
names:
2xx:
- user_id
npx redocly lint
validating /openapi/openapi.yaml...
[1] openapi/components/responses/200.yaml:2:1 at #/properties
Response object must contain a top-level "user_id" property.
...
Error was generated by the response-contains-property rule.
[2] openapi/components/responses/201.yaml:2:1 at #/properties
Response object must contain a top-level "user_id" property.
...
Error was generated by the response-contains-property rule.
[3] openapi/components/responses/202.yaml:2:1 at #/properties
Response object must contain a top-level "user_id" property.
...
Error was generated by the response-contains-property rule.
[4] openapi/components/responses/200.yaml:2:1 at #/properties
Response object must contain a top-level "user_id" property.
...
Error was generated by the response-contains-property rule.
[5] openapi/components/responses/200.yaml:2:1 at #/properties
Response object must contain a top-level "user_id" property.
...
Error was generated by the response-contains-property rule.
/openapi/openapi.yaml: validated in 71ms
❌ Validation failed with 5 errors.
run `openapi lint --generate-ignore-file` to add all problems to the ignore file.
If you're using the Redocly OpenAPI extension for VS Code, this is how the lint errors look in the integrated terminal (Problems tab):
What does the lint output mean
There are three 2xx class responses defined for this guide, and you can see that the rule
has successfully triggered errors with the missing user_id property for all of them.
Yet, three $refs within the OpenAPI definition refer to the 200 response
schema object and one $ref refers to each of the 201 and 202 responses, resulting in
5 errors in total
Case 3 - Multiple responses containing multiple properties
Imagine that your API evolves, and in addition to user_id for successful (200) responses, it
should have created_at and ref_id properties for all other 2xx responses. Let's define this.
rules:
no-unused-components: error
response-contains-property:
severity: error
names:
200:
- user_id
2xx:
- created_at
- ref_id
npx redocly lint
validating /openapi/openapi.yaml...
[1] openapi/components/responses/200.yaml:2:1 at #/properties
Response object must contain a top-level "user_id" property.
...
Error was generated by the response-contains-property rule.
[2] openapi/components/responses/201.yaml:2:1 at #/properties
Response object must contain a top-level "created_at" property.
...
Error was generated by the response-contains-property rule.
[3] openapi/components/responses/201.yaml:2:1 at #/properties
Response object must contain a top-level "ref_id" property.
...
Error was generated by the response-contains-property rule.
[4] openapi/components/responses/202.yaml:2:1 at #/properties
Response object must contain a top-level "created_at" property.
...
Error was generated by the response-contains-property rule.
[5] openapi/components/responses/202.yaml:2:1 at #/properties
Response object must contain a top-level "ref_id" property.
...
Error was generated by the response-contains-property rule.
[6] openapi/components/responses/200.yaml:2:1 at #/properties
Response object must contain a top-level "user_id" property.
...
Error was generated by the response-contains-property rule.
[7] openapi/components/responses/200.yaml:2:1 at #/properties
Response object must contain a top-level "user_id" property.
...
Error was generated by the response-contains-property rule.
/openapi/openapi.yaml: validated in 50ms
❌ Validation failed with 7 errors.
run `openapi lint --generate-ignore-file` to add all problems to the ignore file.
If you're using the Redocly OpenAPI extension for VS Code, this is how the lint errors look in the integrated terminal (Problems tab):
What does the lint output mean
In this example, as there are multiple properties to check within the same response class, the properties defined in a more specific status code take priority over the properties defined in a status code range.
As a result, the user_id is checked exclusively within the 200 status codes
(that have three reference points), whereas created_at and ref_id are checked within
the rest of the 2xx status codes (201 and 202, which have one reference point each),
resulting in 7 errors in total.