You can use Postman to identify any potential security and formatting issues when defining your API.
For all APIs defined in OpenAPI 2.0, the following list describes possible warning messages and potential ways to resolve them.
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. |
swagger: '2.0'
#...
security:
- OAuth2:
- read
- write
securityDefinitions:
OAuth2:
type: oauth2
flow: accessCode
scopes:
read: read object
write: writes object
authorizationUrl: https://example.com/authorize
tokenUrl: https://example.com/token
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. |
swagger: '2.0'
#...
paths:
'/user':
get:
summary: 'Sample endpoint: Returns details about a particular user'
operationId: listUser
security:
- OAuth2:
- read
- write
securityDefinitions:
OAuth2:
type: oauth2
flow: accessCode
scopes:
read: read object
write: writes object
authorizationUrl: https://example.com/authorize
tokenUrl: https://example.com/token
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. |
swagger: '2.0'
#...
securityDefinitions:
basicAuth:
type: basic
security:
- basicAuth: []
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. |
swagger: '2.0'
#...
securityDefinitions:
basicAuth:
type: basic
security:
- basicAuth: []
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. |
swagger: '2.0'
#...
securityDefinitions:
basicAuth:
type: basic
security:
- basicAuth: []
Issue description | Possible fix |
---|---|
The components object of the API doesn't declare any security definitions which can be used in the security field of the API or individual operations. | Security definitions need to be defined in the schema of the component. |
swagger: '2.0'
#...
securityDefinitions:
basicAuth:
type: basic
Issue description | Possible fix |
---|---|
An empty object in the reusable security definition means that no authentication scheme is defined for each operation, anyone can access the API operations without any authentication. | Security definitions need to have at least one item in the object. |
swagger: '2.0'
#...
securityDefinitions:
basicAuth:
type: basic
Issue description | Possible fix |
---|---|
The authentication scheme used in global or operation security field isn't defined in the security definition object. | The scheme used in the security field needs to be defined in the security definition object. |
swagger: '2.0'
#...
securityDefinitions:
basicAuth:
type: basic
security:
- basicAuth: []
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. |
swagger: '2.0'
#...
paths:
/user:
get:
description: 'Returns details about a particular user'
security:
- basicAuth: []
#...
securityDefinitions:
basicAuth:
type: basic
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. |
swagger: '2.0'
#...
paths:
/user:
get:
description: 'Returns details about a particular user'
security:
- basicAuth: []
#...
securityDefinitions:
basicAuth:
type: basic
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. |
swagger: '2.0'
#...
paths:
/user:
get:
description: 'Sample endpoint: Returns details about a particular user'
security:
- basicAuth: []
#...
securityDefinitions:
basicAuth:
type: basic
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 scheme used in the schemes array is HTTPS. |
swagger: '2.0'
#...
host: 'example.com'
schemes:
- https
securityDefinitions:
OAuth2:
type: oauth2
flow: accessCode
authorizationUrl: https://my.auth.example.com/
tokenUrl: https://my.token.example.com/
security:
- OAuth2: []
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 scheme used in the scheme array is HTTPS. |
swagger: '2.0'
#...
host: 'example.com'
schemes:
- https
securityDefinitions:
apiKeyAuth:
type: apiKey
name: api_key
in: header
security:
- apiKeyAuth: []
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 scheme used in the scheme array is HTTPS. |
swagger: '2.0'
#...
host: 'example.com'
schemes:
- https
securityDefinitions:
basicAuth:
type: basic
security:
- basicAuth: []
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 scheme used in the scheme array is HTTPS. |
swagger: '2.0'
#...
host: 'example.com'
schemes:
- https
#...
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 scheme used in the scheme array of the operation is HTTPS. |
swagger: '2.0'
#...
host: 'example.com'
paths:
'/user':
get:
summary: 'Sample endpoint: Returns details about a particular user'
schemes:
- https
security:
- OAuth2: []
#...
securityDefinitions:
OAuth2:
type: oauth2
flow: accessCode
authorizationUrl: https://my.auth.example.com/
tokenUrl: https://my.token.example.com/
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 scheme used in the scheme array of the operation is HTTPS. |
swagger: '2.0'
#...
host: 'example.com'
paths:
'/user':
get:
summary: 'Sample endpoint: Returns details about a particular user'
schemes:
- https
security:
- apiKeyAuth: []
#...
securityDefinitions:
apiKeyAuth:
type: apiKey
name: api_key
in: header
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 scheme used in the scheme array of the operation is HTTPS. |
swagger: '2.0'
#...
host: 'example.com'
paths:
'/user':
get:
summary: 'Sample endpoint: Returns details about a particular user'
schemes:
- https
security:
- BasicAuth: []
#...
securityDefinitions:
BasicAuth:
type: basic
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 scheme used in the scheme array of the operation is HTTPS. |
swagger: '2.0'
#...
host: 'example.com'
paths:
'/user':
get:
summary: 'Sample endpoint: Returns details about a particular user'
schemes:
- https
#...
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. |
swagger: '2.0'
#...
securityDefinitions:
OAuth2:
type: oauth2
flow: accessCode
#...
authorizationUrl: https://example.com/authorize
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. |
swagger: '2.0'
#...
securityDefinitions:
OAuth2:
type: oauth2
flow: accessCode
#...
tokenUrl: https://example.com/token
Issue description | Possible fix |
---|---|
If the global produces field isn't defined, the API could return any form of data. | The produces field needs to be defined in the schema. |
swagger: '2.0'
paths: {}
consumes:
- application/json
produces:
- application/json
Issue description | Possible fix |
---|---|
If the produces field has an empty array, the API can return any type of data by default. | The global produces field needs at least one item with a valid MIME type in the array. |
swagger: '2.0'
paths: {}
produces:
- application/json
...
Issue description | Possible fix |
---|---|
No produces field in the operation means that API can return any type of data by default. | The produces field in any operation needs to have at least one item in the array. |
swagger: '2.0'
paths:
/user/{userId}:
get:
produces:
- application/json
Issue description | Possible fix |
---|---|
If both the global produces field and operation's produces field for any operation aren't defined, anyone can exploit your API. | Define a produces field in the operation if not defined at the global level. |
swagger: '2.0'
paths:
/user/{userId}:
get:
produces:
- application/json
...
...
Issue description | Possible fix |
---|---|
If the global consumes field isn't defined, the API could accept any form of data as input. This could open your API to any number of potential attacks, like buffer overflow, decoding errors, or SQL injection attacks. | The consumes field needs to be defined in the schema. |
swagger: '2.0'
paths: {}
consumes:
- application/json
Issue description | Possible fix |
---|---|
If the consumes field has an empty array, the API can accept any type of input by default. | The global consumes field needs at least one item with valid MIME type in the array. |
swagger: '2.0'
paths: {}
consumes:
- application/json
...
Issue description | Possible fix |
---|---|
No consumes field in the operation means that API can accept any type of input by default. | The consumes field in PUT /PATCH /POST operations needs to have at least one item in the array. |
swagger: '2.0'
paths:
/user/{userId}:
put:
consumes:
- application/json
Issue description | Possible fix |
---|---|
If both the global consumes field and operation's consumes field (for PUT /PATCH /POST ) aren't defined, anyone can exploit your API. | Define a consumes field in the operation if not defined at the global level. |
swagger: '2.0'
paths:
/user/{userId}:
put:
consumes:
- application/json
...
...
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 accessCode flow. Make sure that the OAuth authentication scheme isn't using the implicit flow. |
swagger: '2.0'
#...
securityDefinitions:
OAuth2:
type: oauth2
flow: accessCode
authorizationUrl: https://my.auth.example.com/
tokenUrl: https://my.token.example.com/
scopes:
write: modify data
read: read data
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 accessCode flow. Make sure that the OAuth authentication scheme isn't using the password flow. |
swagger: '2.0'
#...
securityDefinitions:
OAuth2:
type: oauth2
flow: accessCode
authorizationUrl: https://my.auth.example.com/
tokenUrl: https://my.token.example.com/
scopes:
write: modify data
read: read data
This rule category deals with the OpenAPI info object, which has metadata about the API.
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. |
swagger: '2.0'
info:
title: An API name
version: '1.0'
description: An API description
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. |
swagger: '2.0'
info:
title: An API name
version: '1.0'
license:
name: Apache 2.0
url: https://opensource.org/licenses/Apache-2.0
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. |
swagger: '2.0'
info:
title: An API name
version: '1.0'
license:
name: Apache 2.0
url: https://opensource.org/licenses/Apache-2.0
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. |
swagger: '2.0'
info:
title: An API name
version: '1.0'
termsOfService: https://example.com/tos
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. |
swagger: '2.0'
info:
title: An API name
version: '1.0'
contact:
email: support@example.com
url: https://example.com/support
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. |
swagger: '2.0'
info:
title: An API name
version: '1.0'
contact:
name: A contact name
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. |
swagger: '2.0'
info:
title: An API name
version: '1.0'
contact:
email: contact@example.com
swagger: '2.0'
info:
title: An API name
version: '1.0'
contact:
url: https://example.com/support
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. |
swagger: '2.0'
info:
title: An API name
version: '1.0'
contact:
email: contact@example.com
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. |
swagger: '2.0'
info:
title: An API name
version: '1.0'
contact:
url: https://example.com/support
This rule category deals with operations on an API path.
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. |
swagger: '2.0'
# ...
paths:
'/resources':
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. |
swagger: '2.0'
# ...
paths:
/resources:
get:
summary: A GET operation summary
Issue description | Possible fix |
---|---|
One or more operation objects in your API definition has a summary that ends with a period (. ). API documentation tools use the summary as a title, so don't end it with a period. | Remove the final period from all summaries at the operations object level in your API definition. |
swagger: '2.0'
# ...
paths:
/resources:
get:
summary: A GET operation summary
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. |
swagger: '2.0'
# ...
paths:
/resources:
get:
description: A GET operation description
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. |
swagger: '2.0'
# ...
paths:
/resources:
get:
parameters:
- name: status
description: filters resources on their status
in: query
type: string
Issue description | Possible fix |
---|---|
One or more POST operation objects in your API definition don't have a request body. Even though the HTTP protocol permits POST requests without a body, this often hides a design problem. | Add a request body to any POST operation objects. |
swagger: '2.0'
# ...
paths:
/resources:
post:
parameters:
- in: body
name: body
schema:
type: object
Issue description | Possible fix |
---|---|
One or more PUT operation objects in your API definition don't have a request body. 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 to any POST operation objects. |
swagger: '2.0'
# ...
paths:
/resources:
put:
parameters:
- in: body
name: body
schema:
type: object
Issue description | Possible fix |
---|---|
One or more PATCH operation objects in your API definition don't have a request body. Since PATCH operations are used to make partial updates, a PATCH method needs to include a request body. | Add a request body to any PATCH operation objects. |
swagger: '2.0'
# ...
paths:
/resources:
patch:
parameters:
- in: body
name: body
schema:
type: object
Issue description | Possible fix |
---|---|
A schema object in one or more body parameter objects in your API definition don't have an example. It's important to provide an example of the request body 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 field to the schema of all body parameters. |
swagger: '2.0'
# ...
paths:
/resources:
post:
parameters:
- in: body
name: body
schema:
type: object
example:
aProperty: example value
Issue description | Possible fix |
---|---|
The responses object for one or more operation objects in your API definition doesn'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 all operations return a 2xx success status code. |
swagger: '2.0'
# ...
paths:
/resources:
get:
responses:
'200':
description: A success response
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. |
swagger: '2.0'
# ...
paths:
/resources:
get:
responses:
'500':
description: A server error response
Issue description | Possible fix |
---|---|
One or more response objects in your API definition don't have an example. It's important to provide an example of the response 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 examples field to all response objects. |
swagger: '2.0'
# ...
paths:
/resources:
get:
responses:
'200':
description: A success response
examples:
'application/json':
aProperty: example value
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. |
swagger: '2.0'
#...
paths:
/resources:
delete:
responses:
'204':
description: a success response
This rule category deals with how to model various data types.
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 . |
swagger: '2.0'
# ...
paths:
/resources:
post:
parameters:
- name: a resource to create
in: body
schema:
$ref: '#/definitions/ResourceCreate'
responses:
'201':
description: a post success response
schema:
$ref: '#/definitions/Resource'
definitions:
ResourceCreate:
type: object
Resource:
type: object
Issue description | Possible fix |
---|---|
One or more schema objects in the definitions 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. |
swagger: '2.0'
# ...
definitions:
aReusableSchema:
description: a reusable schema description
type: object
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. |
swagger: '2.0'
#...
paths:
/resources:
get:
responses:
'200':
description: a success response
schema:
properties:
aProperty:
description: a property description
type: string
minItems
and maxItems
definedIssue 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. |
swagger: '2.0'
# ...
definitions:
anObject:
properties:
aList:
type: array
minItems: 1
maxItems: 100
items:
type: object
Last modified: 2024/07/01
Additional resources
Blog posts
Public workspaces