OpenAPI 3 security and formatting warnings

You can use Postman to identify any potential security and formatting issues when defining your API.

Warnings for OpenAPI 3

For all APIs defined in OpenAPI 3.0 and 3.1, the following list describes possible warning messages and potential ways to resolve them.

Broken object level authorization

Scope for OAuth scheme used in security field is not defined in the securityScheme declaration

Issue description	Possible fix
The OAuth2 scopes used in the global security field need to be defined in the security schemes field. Otherwise, an attacker can introduce their scopes to fill the gap and exploit the system.	Make sure that all the OAuth2 scopes used are defined in the OAuth2 security scheme.

Resolution

1 security:
2   - OAuth2:
3     - read
4     - write
5 components:
6   securitySchemes:
7     OAuth2:
8       type: oauth2
9       flows:
10         authorizationCode:
11           scopes:
12             read: read objects in your account
13             write: write objects to your account

Scope for OAuth scheme used is not defined in the securityScheme declaration

Issue description	Possible fix
The OAuth2 scopes used in the security field of the operation need to be defined in the security schemes field. Otherwise, an attacker can introduce their scopes to fill the gap and exploit the system.	Make sure that all the OAuth2 scopes used are defined in the OAuth2 security scheme.

Resolution

1 paths:
2   /user:
3     get:
4       summary: 'Sample endpoint: Returns details about a particular user'
5       operationId: listUser
6       security:
7       - OAuth2:
8         - read
9         - write
10 components:
11   securitySchemes:
12     OAuth2:
13       type: oauth2
14       flows:
15         authorizationCode:
16           scopes:
17             read: read objects in your account
18             write: write objects to your account

Broken user authentication

Security field is not defined

Issue description	Possible fix
If the global security field isn’t defined, the API doesn’t require any authentication by default. Anyone can access the API operations that don’t have a security field defined.	The security field needs to be defined in the schema.

Resolution

1 openapi: 3.0.0
2 info:
3 paths:
4 security:
5     - testAuth : []

Security field does not contain any item

Issue description	Possible fix
If the security field has an empty array, no security scheme is applied to the operations by default.	The security field needs to have at least one item in the array.

Resolution

1 openapi: 3.0.0
2 info:
3 paths:
4 security:
5     - testAuth : []

Security field does not contain any scheme

Issue description	Possible fix
An empty object in the security field deactivates the authentication. Without security fields defined for each operation, anyone can access the API operations without any authentication.	Security field array items can’t have an empty object.

Resolution

1 openapi: 3.0.0
2 info:
3 paths:
4 security:
5     - testAuth : []

Security scheme object not defined

Issue description	Possible fix
The components object of the API doesn’t declare any security schemes which can be used in the security field of the API or individual operations.	Security schemes need to be defined in the schema of the component.

Resolution

1 components:
2   securitySchemes:
3     testAuth:
4       type: http
5       scheme: basic

Security scheme object does not contain any scheme

Issue description	Possible fix
An empty object in the reusable security schemes means that no authentication scheme is defined for each operation, anyone can access the API operations without any authentication.	Security schemes need to have at least one item in the object.

Resolution

1 components:
2   securitySchemes:
3     BasicAuth:
4       type: http
5       scheme: basic

Scheme used in security field is not defined in the security scheme object

Issue description	Possible fix
The authentication scheme used in global or operation security field isn’t defined in the security scheme object.	The scheme used in the security field needs to be defined in the security scheme object.

Resolution

1 components:
2   securitySchemes:
3     BasicAuth:
4       type: http
5       scheme: basic
6 #...
7 security:
8 - BasicAuth: []

HTTP authentication scheme is using an unknown scheme

Issue description	Possible fix
The name of the HTTP authentication scheme must be registered in the IANA Authentication Scheme registry.	Make sure that the HTTP authentication scheme registered in the IANA Authentication Scheme registry is used.

Resolution

1 servers:
2   - url: https://my.server.example.com/
3     description: API server
4 #...
5 components:
6   securitySchemes:
7     myAuth:
8       type: http
9       scheme: basic
10 #...
11 security:
12   - myAuth: []

Security field for the operation does not contain any item

Issue description	Possible fix
No security scheme is applied to the API operation by default.	The security field in any operation needs to have at least one item in the array.

Resolution

1 openapi: 3.0.0
2 info:
3   title: Example API
4   version: '1.0'
5 paths:
6  /user:
7   get:
8    security:
9    - BasicAuth : []
10    responses:
11     default:
12      description: Example
13 components:
14  securitySchemes:
15   BasicAuth:
16    type: http
17    scheme: basic

Security field for the operation does not contain any scheme

Issue description	Possible fix
An empty object in the security field deactivates the authentication for the operation. Anyone can access the API operation without any authentication.	Specify at least one security requirement in the operation.

Resolution

1 openapi: 3.0.0
2 info:
3   title: Example API
4   version: '1.0'
5 paths:
6  /user:
7   get:
8    security:
9    - BasicAuth : []
10    responses:
11     default:
12      description: Example
13 components:
14  securitySchemes:
15   BasicAuth:
16    type: http
17    scheme: basic

Operation does not enforce any security scheme

Issue description	Possible fix
If both the global security field and operation’s security field aren’t defined, anyone can access the API without any authentication.	Define a security field in the operation.

Resolution

1  openapi: 3.0.0
2 info:
3   title: Example API
4   version: '1.0'
5 paths:
6  /user:
7   get:
8    security:
9    - BasicAuth : []
10    responses:
11     default:
12      description: Example
13 components:
14  securitySchemes:
15   BasicAuth:
16    type: http
17    scheme: basic

Excessive data exposure

API accepts credentials from OAuth authentication in plain text

Issue description	Possible fix
The access tokens are sent as plain text over an unencrypted network. Attackers can intercept the access tokens by listening to the network traffic in a public Wi-Fi network.	Make sure that the server URL is a valid URL and uses HTTPS protocol.

Resolution

1 servers:
2   - url: https://my.api.example.com/
3     description: API server
4 # ...
5 components:
6   securitySchemes:
7     OAuth2:
8       type: oauth2
9 # ...
10 security:
11   - OAuth2:
12       - write
13       - read

API accepts credentials from OpenID Connect authentication in plain text

Issue description	Possible fix
The credentials are sent as plain text over an unencrypted network. Attackers can intercept the access tokens by listening to the network traffic in a public Wi-Fi network.	Make sure that the server URL is a valid URL and uses HTTPS protocol.

Resolution

1 components:
2  securitySchemes:
3   OpenIdScheme:
4    type: openIdConnect
5    openIdConnectUrl: https://example.com/connect
6 paths:
7  '/pets':
8   post:
9    operationId: addPet
10    servers:
11    - url: https://example.com/
12      description: API server
13    security:
14    - OpenIdScheme: []

API accepts credentials from OAuth 1.0 authentication in plain text

Issue description	Possible fix
The authentication tokens are sent as plain text over an unencrypted channel. Attackers can intercept the token by listening to the network traffic in a public Wi-Fi network.	Make sure that the server URL is a valid URL and uses HTTPS protocol.

Resolution

1 servers:
2   - url: https://my.api.example.com/
3     description: API server
4 #...
5 components:
6   securitySchemes:
7     OAuth1:
8       type: http
9       scheme: oauth
10 #...
11 security:
12   - OAuth1: []

API accepts API key in plain text

Issue description	Possible fix
API keys are sent as plain text over an unencrypted channel. Attackers can intercept API key by listening to the network traffic in a public Wi-Fi network.	Make sure that the server URL is a valid URL and uses HTTPS protocol.

Resolution

1 servers:
2   - url: https://my.api.example.com/
3     description: API server
4 #...
5 components:
6   securitySchemes:
7     AuthKeyAuth:
8       type: apiKey
9       name: api-key
10       in: header
11 #...
12 security:
13   - AuthKeyAuth: []

API accepts auth credentials in plain text

Issue description	Possible fix
The credentials are sent as plain text over an unencrypted network. Attackers can intercept the credentials by listening to the network traffic in a public Wi-Fi network.	Make sure that the server URL is a valid URL and uses HTTPS protocol.

Resolution

1 servers:
2 - url: https://example.com/
3   description: Example server
4 components:
5  securitySchemes:
6   BasicAuth:
7    type: http
8    scheme: basic
9 security:
10 - BasicAuth: []

Global server URL uses HTTP protocol

Issue description	Possible fix
The server supports unencrypted HTTP connections, all requests and responses will be transmitted in the open. Anyone listening to the network traffic while the calls are being made can intercept them.	Make sure that the server URL is a valid URL and uses HTTPS protocol.

Resolution

1 servers:
2   - url: https://my.api.example.com/
3     description: API server
4 # ...
5 components:
6   securitySchemes:
7     OAuth2:
8       type: oauth2
9 # ...
10 security:
11   - OAuth2:
12       - write
13       - read

Operation accepts credentials from OAuth authentication in plain text

Issue description	Possible fix
The API operation accepts the access tokens from a flow that are transported in plain text over an unencrypted channel. Attackers can intercept API calls and retrieve the unencrypted tokens. They can then use the tokens to make other API calls.	Make sure that the server URL of the operation is a valid URL and uses HTTPS protocol.

Resolution

1 components:
2   securitySchemes:
3     OAuth2:
4       type: oauth2
5 paths:
6   '/pets':
7     post:
8       operationId: addPet
9       servers:
10       - url: https://my.api.example.com/
11         description: API server

Operation accepts credentials from OpenID Connect authentication as plain text

Issue description	Possible fix
The credentials for an operation are sent as plain text over an unencrypted network. Attackers can intercept the access tokens by listening to the network traffic in a public Wi-Fi network.	Make sure that the server URL of the operation is a valid URL and uses HTTPS protocol.

Resolution

1 components:
2   securitySchemes:
3     OpenIdScheme:
4       type: openIdConnect
5       openIdConnectUrl: https://my.api.openidconnect.example.com/
6 paths:
7   '/pets':
8     post:
9       operationId: addPet
10       servers:
11       - url: https://my.api.example.com/
12         description: API server

Operation accepts credentials from OAuth 1.0 authentication in plain text

Issue description	Possible fix
The API operation accepts the authorization tokens that are transported as plain text over an unencrypted channel. Attackers can intercept API calls and retrieve the unencrypted tokens to make other API calls.	Make sure that the server URL of the operation is a valid URL and uses HTTPS protocol.

Resolution

1 paths:
2   '/pets':
3     post:
4       servers:
5       - url: https://example.com/
6         description: Example server
7 #...
8 components:
9   securitySchemes:
10     OAuth1:
11       type: http
12       scheme: oauth
13 #...
14 security:
15   - OAuth1: []

Operation accepts API key in plain text

Issue description	Possible fix
The API operation accepts API keys that are transported in plain text over an unencrypted channel. Attackers can intercept API calls and retrieve the API key to make other API calls.	Make sure that the server URL of the operation is a valid URL and uses HTTPS protocol.

Resolution

1 paths:
2   '/pets':
3     post:
4       servers:
5       - url: https://example.com/
6         description: Example server
7 # ...
8 components:
9   securitySchemes:
10     AuthKeyAuth:
11       type: apiKey
12       name: api-key
13       in: header
14 # ...
15 security:
16   - AuthKeyAuth: []

Operation accepts authentication credentials in plain text

Issue description	Possible fix
The API operation accepts the credentials that are transported in plain text over an unencrypted channel. Attackers can intercept API calls and retrieve the unencrypted tokens. They can then use the tokens to make other API calls.	Make sure that the server URL of the operation is a valid URL and uses HTTPS protocol.

Resolution

1 components:
2  securitySchemes:
3   BasicAuth:
4    type: http
5    scheme: basic
6 paths:
7  '/pets':
8   post:
9    operationId: addPet
10    servers:
11    - url: https://example.com/
12      description: Example server
13    security:
14    - BasicAuth: []

Server URL of the operation is using HTTP protocol

Issue description	Possible fix
The API operation supports unencrypted HTTP connections, all requests and responses will be transmitted in the open. Anyone listening to the network traffic while the calls are being made can intercept them.	Make sure that the server URL of the operation is a valid URL and uses HTTPS protocol.

Resolution

1 get:
2   operationId: getPetsById
3   servers:
4     - url: https://my.api.example.com/

Authorization URL uses HTTP protocol; credentials will be transferred as plain text

Issue description	Possible fix
OAuth authorization credentials are transported over an unencrypted channel. Anyone listening to the network traffic while the calls are being made can intercept them.	Make sure that the authorization URL is a valid URL and follows HTTPS protocol.

Resolution

1 components:
2   securitySchemes:
3      OauthScheme:
4         type: oauth2
5         flows:
6           authorizationCode:
7             authorizationUrl: https://my.auth.example.com/

Token URL uses HTTP protocol

Issue description	Possible fix
OAuth authentication tokens are transported over an unencrypted channel. Anyone listening to the network traffic while the token is being sent can intercept it.	Make sure that the token URL is a valid URL and follows HTTPS protocol.

Resolution

1 components:
2   securitySchemes:
3      OauthScheme:
4         type: oauth2
5         flows:
6           authorizationCode:
7             tokenUrl: https://my.token.example.com/

Refresh URL uses HTTP protocol

Issue description	Possible fix
OAuth authentication refresh tokens are transported over an unencrypted channel. Anyone listening to the network traffic while the token is being sent can intercept it.	Make sure that the refresh URL is a valid URL and follows HTTPS protocol.

Resolution

1 components:
2   securitySchemes:
3     OauthFlow:
4       type: oauth2
5       flows:
6         authorizationCode
7           authorizationUrl: https://my.auth.example.com/
8           tokenUrl: https://my.token.example.com/
9           refreshUrl: https://my.refresh.example.com/
10           scopes:
11             write: modify data
12             read: read data

OpenID Connect URL uses HTTP protocol

Issue description	Possible fix
OpenID Connect access tokens & open Ids are transported over an unencrypted channel. Anyone listening to the network traffic while the calls are being made can intercept them.	Make sure that the OpenID connect URL is a valid URL and follows HTTPS protocol.

Resolution

1 components:
2   securitySchemes:
3     OpenIdScheme:
4       type: openIdConnect
5       openIdConnectUrl: https://example.com/connect
6 #...
7 security:
8 - OpenIdScheme: []

Improper assets management

Deprecated OAuth 1.0 scheme is used

Issue description	Possible fix
Security scheme uses OAuth 1.0 authentication which has been deprecated and replaced by OAuth 2.0.	Make sure that the security scheme isn’t using the deprecated OAuth 1.0 authentication.

Resolution

1 components:
2   securitySchemes:
3     OauthFlow:
4       type: oauth2
5       flows:
6         authorizationCode:
7           authorizationUrl: https://my.auth.example.com/
8           tokenUrl: https://my.token.example.com/
9           scopes:
10             write: modify data
11             read: read data

OAuth authentication uses the deprecated implicit flow

Issue description	Possible fix
In OAuth implicit flow, authorization server issues access tokens in the authorization request’s response. Attackers can intercept API calls and retrieve the access tokens to make other API calls.	It’s recommended to use authorizationCode flow. Make sure that the OAuth authentication scheme isn’t using the implicit flow.

Resolution

1 components:
2   securitySchemes:
3     OauthFlow:
4       type: oauth2
5       flows:
6         authorizationCode:
7           authorizationUrl: https://my.auth.example.com/
8           tokenUrl: https://my.token.example.com/
9           scopes:
10             write: modify data
11             read: read data

OAuth authentication uses the deprecated password flow

Issue description	Possible fix
OAuth password grant flow uses the user’s credentials to retrieve the access token. Attackers can intercept API calls and retrieve the access tokens to make other API calls.	It’s recommended to use authorizationCode flow. Make sure that the OAuth authentication scheme isn’t using the password grant flow.

Resolution

1 components:
2   securitySchemes:
3     OauthFlow:
4       type: oauth2
5       flows:
6         authorizationCode:
7           authorizationUrl: https://my.auth.example.com/
8           tokenUrl: https://my.token.example.com/
9           scopes:
10             write: modify data
11             read: read data

API information

This rule category deals with the OpenAPI info object, which has metadata about the API.

The info object should have a description

Issue description

Possible fix

Your API definition’s info object doesn’t have a description. Although a description isn’t required, including one enables you to provide your API’s consumers with information about what the API does and how to use it. This can be anything from a short description to a long explanation of possible uses cases. For your organization, defining the API’s description during the design phase can help set the boundaries of the API.

Add a description to your API definition’s info object.

Resolution

1 openapi: '3.0.3'
2 info:
3   title: An API name
4   version: '1.0'
5   description: An API description

The info object should have a license

Issue description	Possible fix
Your API definition’s info object doesn’t have a license object, which helps your API’s consumers know how the API can be copied and used.	Add a license object to your API definition’s info object.

Resolution

1 openapi: '3.0.3'
2 info:
3   title: An API name
4   version: '1.0'
5   license:
6     name: Apache 2.0
7     url: https://opensource.org/licenses/Apache-2.0

The info object should have a license URL

Issue description	Possible fix
Your API definition’s license object doesn’t have a license URL, which provides a link to a web page that describes the license. Although a license URL isn’t required, a license name alone may not be not enough information for your API’s consumers, especially when you use a custom license.	Add a URL to your API definition’s license object.

Resolution

1 openapi: '3.0.3'
2 info:
3   title: An API name
4   version: '1.0'
5   license:
6     name: Apache 2.0
7     url: https://opensource.org/licenses/Apache-2.0

The info object should have a terms of service

Issue description	Possible fix
Your API definition’s info object doesn’t have the URL of the API’s Terms of Service. A terms of service is often mandatory for public APIs. It’s also recommended that private APIs provide a link to a Terms and Conditions web page.	Add the URL of the API’s Terms of Service to your API definition’s info object.

Resolution

1 openapi: '3.0.3'
2 info:
3   title: An API name
4   version: '1.0'
5   termsOfService: https://example.com/tos

API must have contact information available

Issue description	Possible fix
Your API definition’s info object doesn’t have a contact object, which has contact information like a name, email address, or URL. Contact information defines a designated owner for each of your organization’s APIs. The contact data may be used directly by your API’s consumers, or through an API portal or catalog.	Add a contact object to your API definition’s info object.

Resolution

1 openapi: '3.0.3'
2 info:
3   title: An API name
4   version: '1.0'
5   contact:
6     email: support@example.com
7     url: https://example.com/support

API must have a contact name available

Issue description	Possible fix
Your API definition’s contact object doesn’t have a contact name. Although a contact name isn’t required, it helps your API’s consumers understand who owns the API. It also makes your organization consider the API’s ownership.	Add a name to your API definition’s contact object.

Resolution

1 openapi: '3.0.3'
2 info:
3   title: An API name
4   version: '1.0'
5   contact:
6     name: A contact name

API must have a contact URL or email available

Issue description	Possible fix
Your API definition’s contact object doesn’t have a contact URL or email address. Although a contact URL or email aren’t required, including one or both gives your API’s consumers a way to contact your organization or the API owner.	Add a contact URL, an email address, or both to your API definition’s contact object.

Resolution

1 openapi: '3.0.3'
2 info:
3   title: An API name
4   version: '1.0'
5   contact:
6     email: contact@example.com

1 openapi: '3.0.3'
2 info:
3   title: An API name
4   version: '1.0'
5   contact:
6     url: https://example.com/support

API must have a contact email available

Issue description	Possible fix
Your API definition’s contact object doesn’t have an email address. Although a contact email isn’t required, including one gives your API’s consumers a way to contact your organization or the API owner.	Add an email address to your API definition’s contact object.

Resolution

1 openapi: '3.0.3'
2 info:
3   title: An API name
4   version: '1.0'
5   contact:
6     email: support@example.com

API must have a contact URL available

Issue description	Possible fix
Your API definition’s contact object doesn’t have a contact URL. Although a contact URL isn’t required, including one gives your API’s consumers a way to contact your organization or the API owner.	Add a URL to your API definition’s contact object.

Resolution

1 openapi: '3.0.3'
2 info:
3   title: An API name
4   version: '1.0'
5   contact:
6     url: https://example.com/support

Operations

This rule category deals with operations on an API path.

There should be no trailing slashes on paths

Issue description	Possible fix
One or more path item objects in your API definition’s paths object have a trailing slash at the end of the path. Some tools treat a path that ends with a trailing slash (`/path/`) differently from the way that they treat paths without a trailing slash (`/path`), which can lead to problems that require long hours of debugging.	Remove any trailing slashes from paths in your API definition’s paths object.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   '/resources':

All operations should have summaries

Issue description	Possible fix
One or more operation objects in your API definition don’t have a summary. A summary of what the operation does provides your API’s consumers with important context that the HTTP method and path don’t provide on their own. Many organizations use the API operation description that they create during the define phase of the API development process as the summary.	Add a summary for each operation object.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     get:
6       summary: A GET operation summary

Operation summaries shouldn’t end with a period

Issue description	Possible fix
One or more operation objects in your API definition have a summary that ends with a period (`.`). API documentation tools use the summary as a title, so it shouldn’t end with a period.	Remove the final period from all summaries at the operations object level in your API definition.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     get:
6       summary: A GET operation summary

All operations should have descriptions

Issue description	Possible fix
One or more operation objects in your API definition don’t have a description. When the resource path, HTTP method, and summary don’t provide enough context for your API’s consumers, a description can provide them with useful information about the API operation and its behavior.	Add a description for each operation object.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     get:
6       description: A GET operation description

All parameters should have descriptions

Issue description	Possible fix
One or more parameter objects in an operations object in your API definition don’t have a `description` field. When the API name and context don’t provide enough information for your API’s consumers, a description can provide them with useful information about the parameter.	Add a `description` field for each parameter object.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     get:
6       parameters:
7         - name: status
8           description: Filters resources on their status
9           in: query
10           schema:
11             type: string

All parameters should have examples

Issue description	Possible fix
One or more parameter objects in an operations object in your API definition don’t have an `example` or `examples` field. It’s important to provide undocumented examples (using the `example` property) or documented examples (using the `examples` property) to help your API’s consumers understand what data to provide. It may also help them to generate mock servers or a collection.	Add an `example` or `examples` field to provide your API’s consumers with an example of the parameter’s potential value.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     get:
6       parameters:
7         - name: status
8           description: Filters resources on their status
9           in: query
10           example: done
11           schema:
12             type: string

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     get:
6       parameters:
7         - name: status
8           description: Filters resources on their status
9           in: query
10           examples:
11             anExample:
12               summary: An example
13               description: A description of an example
14               value: done
15           schema:
16             type: string

POST methods should have request bodies

Issue description	Possible fix
One or more POST operation objects in your API definition don’t have a request body object. Even though the HTTP protocol permits POST requests without a body, this often hides a design problem.	Add a request body object to any POST operation objects.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     post:
6       requestBody:
7         content:
8           'application/json':
9             schema:
10               type: object

PUT methods should have request bodies

Issue description	Possible fix
One or more PUT operation objects in your API definition don’t have a request body object. Since a PUT operation is often used to replace or create something, not having a request body might be an error. However, this use might make sense in some cases (for example, to link two resources with a PUT, like `/resource-ones/id1/other-resources/id2`).	Add a request body object to any POST operation objects.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     put:
6       requestBody:
7         content:
8           'application/json':
9             schema:
10               type: object

PATCH methods should have request bodies

Issue description	Possible fix
One or more PATCH operation objects in your API definition don’t have a request body object. Since PATCH operations are used to make partial updates, a PATCH method needs to include a request body.	Add a request body object to any PATCH operation objects.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     patch:
6       requestBody:
7         content:
8           'application/json':
9             schema:
10               type: object

All request bodies should have examples

Issue description	Possible fix
One or more request body objects in your API definition don’t have an example. It’s important to provide undocumented examples (using the `example` property) or documented examples (using the `examples` property) to help your API’s consumers understand what data they’ll receive. It may also help them to generate mock servers or a collection.	Add an `example` or `examples` field to all request body objects.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     post:
6       requestBody:
7         content:
8           'application/json':
9             schema:
10               # ...
11             example:
12               aProperty: example value

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     post:
6       requestBody:
7         content:
8           'application/json':
9             schema:
10               # ...
11             examples:
12               anExample:
13                 summary: An example
14                 description: This is an example description
15                 value:
16                   aProperty: example value

Operation should return a 2xx HTTP status code

Issue description	Possible fix
The responses object for one or more operation objects in your API definition don’t have a `2xx` class status code. Operations are expected to succeed and return a `2xx` success HTTP status code. It’s rare for an operation to return a different code, such as a `3xx` redirect code, instead.	Make sure that operations return a `2xx` success status code.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     get:
6       responses:
7         '200':
8           description: A success response

Operation should return a 5xx HTTP status code

Issue description	Possible fix
The responses object for one or more operation objects in your API definition doesn’t have a `5xx` class status code. Since operations may fail, they need to return a `5xx` server error HTTP status code.	Make sure that all operations return a `5xx` status code.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     get:
6       responses:
7         '500':
8           description: A server error response

All responses should have examples

Issue description	Possible fix
One or more response objects in your API definition don’t have an example. It’s important to provide undocumented examples (using the `example` property) or documented examples (using the `examples` property) to help your API’s consumers understand what data they’ll receive. It may also help them to generate mock servers or a collection.	Add an `example` or `examples` field to all response objects.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     get:
6       responses:
7         '200':
8           description: A success response
9           content:
10             'application/json':
11               schema:
12                 # ...
13               example:
14                 aProperty: example

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     get:
6       responses:
7         '200':
8           description: A success response
9           content:
10             'application/json':
11               schema:
12                 # ...
13               examples:
14                 anExample:
15                   summary: An example
16                   description: This is an example description
17                   value:
18                     aProperty: example value

A 204 response can’t have a body

Issue description	Possible fix
The responses object for one or more DELETE operation objects has a `204` HTTP status code but also defines a response body. A `204` status means “no content,” so there shouldn’t be a response body defined.	Make sure that DELETE methods with a `204` status code don’t have a response body.

Resolution

1 openapi: '3.0.3'
2 #...
3 paths:
4   /resources:
5     delete:
6       responses:
7         '204':
8           description: a success response

Models

This rule category deals with how to model various data types.

A schema property should reference a reusable schema

Issue description	Possible fix
A schema property in one or more response objects or body parameter objects doesn’t reference a reusable schema. A schema reference (`$ref`) that targets reusable schemas in `definitions` supports design consistency and OpenAPI document and API documentation readability, and facilitates maintainability by avoiding duplication of models.	Consolidate all your responses and body parameter schemas into `definitions`.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     get:
6       responses:
7         '200':
8           description: a success response
9           content:
10             'application/json':
11               schema:
12                 $ref: '#/components/schemas/Resources'
13 components:
14   schemas:
15     Resources:
16       type: object

All reusable schemas should have descriptions

Issue description	Possible fix
One or more schema objects in the components object don’t have a `description`. When the schema name and context don’t provide enough information for your API’s designers and consumers, a description can provide them with useful information about the reusable schema.	Add a `description` for every reusable schema in your API definition.

Resolution

1 openapi: '3.0.3'
2 # ...
3 components:
4   schemas:
5     aReusableSchema:
6       description: A reusable schema description
7       type: object

All schema properties should have descriptions

Issue description Possible fix

One or more properties in a schema object in your API definition don’t have a description. When the schema name and context don’t provide enough information for your API’s consumers, a description can provide them with useful information about the element. A complicated description may indicate a problem in the API’s definition or design, so spending the time to create a description can be clarifying. Add a description for every property in your schema object.

Resolution

1 openapi: '3.0.3'
2 # ...
3 paths:
4   /resources:
5     get:
6       responses:
7         '200':
8           description: A success response
9           content:
10             'application/json':
11               schema:
12                 properties:
13                   aProperty:
14                     description: A property description
15                     type: string

Arrays must have `minItems` and `maxItems` defined

Issue description	Possible fix
One or more schema objects in your API definition have an array type property but don’t define `minItem` or `maxItem`. Consumers and providers can’t handle an infinite number of elements. Setting the minimum and maximum boundaries helps in defining limits and enabling pagination.	Make sure that properties that have array type in your API definition have `minItem` and `maxItem` defined.

Resolution

1 openapi: '3.0.3'
2 # ...
3 components:
4   schemas:
5     anObject:
6       properties:
7         aList:
8           type: array
9           minItems: 1
10           maxItems: 100
11           items:
12             type: object