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:

1. Single response containing one property
2. Multiple responses containing one property
3. Multiple responses containing multiple properties

Let's get started!

Before you begin

• Use the openapi-starter repository to set up a basic project that we will use for this guide.
• Download the modified project files and use them to replace the corresponding files in the openapi folder:

.
└── openapi
    ├── components
    │   └── responses
    │       ├── 200.yaml
    │       ├── 201.yaml
    │       └── 202.yaml
    └── paths
        ├── path-item-with-examples.yaml
        ├── path-item.yaml
        └── users_{username}.yaml

• If you're using VS Code as your favorite code editor, we recommend you install the Redocly OpenAPI VS Code extension .

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.

1. Open the .redocly.yaml in the project folder
2. 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.