OpenAPI 2.0 规则
在定义 API 时，你可以使用 Postman 来识别任何潜在的安全和格式问题。
OpenAPI 2.0 的警告
对于 OpenAPI 2.0 中定义的所有 API，以下列表描述了可能的警告消息和可能的解决方法。
- 损坏的对象级别授权
- securityDefinition 声明中未定义安全字段中使用的 OAuth 方案的范围
- 使用的 OAuth 方案的范围未在 securityDefinition 声明中定义
- 损坏的用户身份验证
- 未定义安全字段
- 安全字段不包含任何项目
- 安全字段不包含任何方案
- 未定义安全定义对象
- 安全定义对象不包含任何方案
- 安全字段中使用的方案未在安全定义对象中定义
- 操作的安全字段不包含任何项目
- 操作的安全字段不包含任何方案
- 操作不强制执行任何安全方案
- 过多的数据暴露
- API 以纯文本形式接受来自 OAuth 身份验证的凭据
- API 接受纯文本形式的 API 密钥
- API 接受纯文本形式的基本身份验证凭据
- 全局方案定义了 HTTP 方案
- 操作以纯文本形式接受来自 OAuth 身份验证的凭据
- 操作接受纯文本形式的 API 密钥
- 操作接受纯文本形式的基本身份验证凭据
- 操作的方案定义了 HTTP 方案
- 授权 URL 使用 HTTP 协议；凭据将以纯文本形式传输
- Token URL 使用 HTTP 协议
- Produces 字段未定义
- Produces 字段不包含任何项目
- 操作的生产字段不包含任何项目
- 操作不包含 produces 字段
- 注射
- Consumes 字段未定义
- Consumes 字段不包含任何项目
- 操作的 Consumes 字段不包含任何项目
- 操作不包含消耗字段
- 资产管理不当
- OAuth 身份验证使用已弃用的隐式流程
- OAuth 身份验证使用已弃用的密码流程
- API 信息
- 信息对象应该有一个描述
- 信息对象应该有许可证
- 信息对象应该有一个许可证 URL
- 信息对象应该有服务条款
- API 必须有可用的联系信息
- API 必须有可用的联系人姓名
- API 必须有可用的联系 URL 或电子邮件
- API 必须有可用的联系电子邮件
- API 必须有可用的联系 URL
- 操作
- 路径上不应有尾部斜杠
- 所有的操作都应该有总结
- 操作摘要不应以句号结尾
- 所有操作都应该有描述
- 所有参数都应该有说明
- POST 方法应该有请求体
- PUT 方法应该有请求主体
- PATCH 方法应该有请求主体
- 所有请求主体都应该有示例
- 操作应返回 2xx HTTP 状态代码
- 操作应返回 5xx HTTP 状态代码
- 所有回复都应该有例子
- 204 响应不能有正文
- 楷模
- 架构属性应引用可重用架构
- 所有可重用的模式都应该有描述
- 所有模式属性都应该有描述
- 数组必须有
minItems并maxItems定义
securityDefinition 声明中未定义安全字段中使用的 OAuth 方案的范围
| 问题描述 | 可能的修复 |
|---|---|
| 全局安全字段中使用的 OAuth2 范围需要在安全方案字段中定义。否则，攻击者可以引入他们的范围来填补空白并利用系统。 | 确保使用的所有 OAuth2 范围都在 OAuth2 安全方案中定义。 |
解决
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
使用的 OAuth 方案的范围未在 securityDefinition 声明中定义
| 问题描述 | 可能的修复 |
|---|---|
| 在操作的安全字段中使用的 OAuth2 范围需要在安全方案字段中定义。否则，攻击者可以引入他们的范围来填补空白并利用系统。 | 确保使用的所有 OAuth2 范围都在 OAuth2 安全方案中定义。 |
解决
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
损坏的用户身份验证
未定义安全字段
| 问题描述 | 可能的修复 |
|---|---|
| 如果未定义全局安全字段，则默认情况下 API 不需要任何身份验证。任何人都可以访问未定义安全字段的 API 操作。 | 安全字段需要在模式中定义。 |
解决
swagger: '2.0'
#...
securityDefinitions:
basicAuth:
type: basic
security:
- basicAuth: []
安全字段不包含任何项目
| 问题描述 | 可能的修复 |
|---|---|
| 如果安全字段有一个空数组，默认情况下没有安全方案应用于操作。 | 安全字段需要在数组中至少有一项。 |
解决
swagger: '2.0'
#...
securityDefinitions:
basicAuth:
type: basic
security:
- basicAuth: []
安全字段不包含任何方案
| 问题描述 | 可能的修复 |
|---|---|
| 安全字段中的空对象会停用身份验证。如果没有为每个操作定义安全字段，任何人都可以在没有任何身份验证的情况下访问 API 操作。 | 安全字段数组项不能有空对象。 |
解决
swagger: '2.0'
#...
securityDefinitions:
basicAuth:
type: basic
security:
- basicAuth: []
未定义安全定义对象
| 问题描述 | 可能的修复 |
|---|---|
| API 的组件对象没有声明任何可以在 API 的安全字段或单个操作中使用的安全定义。 | 安全定义需要在组件的模式中定义。 |
解决
swagger: '2.0'
#...
securityDefinitions:
basicAuth:
type: basic
安全定义对象不包含任何方案
| 问题描述 | 可能的修复 |
|---|---|
| 可重用安全定义中的空对象意味着没有为每个操作定义身份验证方案，任何人都可以访问 API 操作而无需任何身份验证。 | 安全定义需要在对象中至少有一项。 |
解决
swagger: '2.0'
#...
securityDefinitions:
basicAuth:
type: basic
安全字段中使用的方案未在安全定义对象中定义
| 问题描述 | 可能的修复 |
|---|---|
| 全局或操作安全字段中使用的身份验证方案未在安全定义对象中定义。 | 安全域中使用的方案需要在安全定义对象中定义。 |
解决
swagger: '2.0'
#...
securityDefinitions:
basicAuth:
type: basic
security:
- basicAuth: []
操作的安全字段不包含任何项目
| 问题描述 | 可能的修复 |
|---|---|
| 默认情况下，没有安全方案应用于 API 操作。 | 任何操作中的安全字段都需要在数组中至少有一项。 |
解决
swagger: '2.0'
#...
paths:
/user:
get:
description: 'Returns details about a particular user'
security:
- basicAuth: []
#...
securityDefinitions:
basicAuth:
type: basic
操作的安全字段不包含任何方案
| 问题描述 | 可能的修复 |
|---|---|
| 安全字段中的空对象会停用操作的身份验证。任何人都可以访问 API 操作而无需任何身份验证。 | 在操作中指定至少一项安全要求。 |
解决
swagger: '2.0'
#...
paths:
/user:
get:
description: 'Returns details about a particular user'
security:
- basicAuth: []
#...
securityDefinitions:
basicAuth:
type: basic
操作不强制执行任何安全方案
| 问题描述 | 可能的修复 |
|---|---|
| 如果全局安全字段和操作的安全字段都没有定义，任何人都可以访问 API 而无需任何身份验证。 | 在操作中定义一个安全字段。 |
解决
swagger: '2.0'
#...
paths:
/user:
get:
description: 'Sample endpoint: Returns details about a particular user'
security:
- basicAuth: []
#...
securityDefinitions:
basicAuth:
type: basic
过多的数据暴露
API 以纯文本形式接受来自 OAuth 身份验证的凭据
| 问题描述 | 可能的修复 |
|---|---|
| 访问令牌以纯文本形式通过未加密的网络发送。攻击者可以通过监听公共 Wi-Fi 网络中的网络流量来拦截访问令牌。 | 确保方案数组中使用的方案是 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: []
API 接受纯文本形式的 API 密钥
| 问题描述 | 可能的修复 |
|---|---|
| API 密钥通过未加密的通道以纯文本形式发送。攻击者可以通过监听公共 Wi-Fi 网络中的网络流量来拦截 API 密钥。 | 确保方案数组中使用的方案是 HTTPS。 |
解决
swagger: '2.0'
#...
host: 'example.com'
schemes:
- https
securityDefinitions:
apiKeyAuth:
type: apiKey
name: api_key
in: header
security:
- apiKeyAuth: []
API 接受纯文本形式的基本身份验证凭据
| 问题描述 | 可能的修复 |
|---|---|
| 凭据以纯文本形式通过未加密的网络发送。攻击者可以通过监听公共 Wi-Fi 网络中的网络流量来拦截凭据。 | 确保方案数组中使用的方案是 HTTPS。 |
解决
swagger: '2.0'
#...
host: 'example.com'
schemes:
- https
securityDefinitions:
basicAuth:
type: basic
security:
- basicAuth: []
全局方案定义了 HTTP 方案
| 问题描述 | 可能的修复 |
|---|---|
| 服务器支持未加密的 HTTP 连接，所有请求和响应都将在公开传输。任何在通话过程中监听网络流量的人都可以拦截它们。 | 确保方案数组中使用的方案是 HTTPS。 |
解决
swagger: '2.0'
#...
host: 'example.com'
schemes:
- https
#...
操作以纯文本形式接受来自 OAuth 身份验证的凭据
| 问题描述 | 可能的修复 |
|---|---|
| API 操作接受来自流的访问令牌，这些访问令牌通过未加密的通道以纯文本格式传输。攻击者可以拦截 API 调用并检索未加密的令牌。然后他们可以使用令牌进行其他 API 调用。 | 确保操作的方案数组中使用的方案是 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/
操作接受纯文本形式的 API 密钥
| 问题描述 | 可能的修复 |
|---|---|
| API 操作接受通过未加密通道以纯文本格式传输的 API 密钥。攻击者可以拦截 API 调用并检索 API 密钥以进行其他 API 调用。 | 确保操作的方案数组中使用的方案是 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
操作接受纯文本形式的基本身份验证凭据
| 问题描述 | 可能的修复 |
|---|---|
| API 操作接受通过未加密通道以纯文本格式传输的凭据。攻击者可以拦截 API 调用并检索未加密的令牌。然后他们可以使用令牌进行其他 API 调用。 | 确保操作的方案数组中使用的方案是 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
操作的方案定义了 HTTP 方案
| 问题描述 | 可能的修复 |
|---|---|
| API 操作支持未加密的 HTTP 连接，所有请求和响应都将公开传输。任何在通话过程中监听网络流量的人都可以拦截它们。 | 确保操作的方案数组中使用的方案是 HTTPS。 |
解决
swagger: '2.0'
#...
host: 'example.com'
paths:
'/user':
get:
summary: 'Sample endpoint: Returns details about a particular user'
schemes:
- https
#...
授权 URL 使用 HTTP 协议；凭据将以纯文本形式传输
| 问题描述 | 可能的修复 |
|---|---|
| OAuth 授权凭据通过未加密的通道传输。任何在通话过程中监听网络流量的人都可以拦截它们。 | 请确保授权 URL 是有效的 URL 并遵循 HTTPS 协议。 |
解决
swagger: '2.0'
#...
securityDefinitions:
OAuth2:
type: oauth2
flow: accessCode
#...
authorizationUrl: https://example.com/authorize
Token URL 使用 HTTP 协议
| 问题描述 | 可能的修复 |
|---|---|
| OAuth 身份验证令牌通过未加密的通道传输。发送令牌时监听网络流量的任何人都可以拦截它。 | 确保令牌 URL 是有效的 URL 并遵循 HTTPS 协议。 |
解决
swagger: '2.0'
#...
securityDefinitions:
OAuth2:
type: oauth2
flow: accessCode
#...
tokenUrl: https://example.com/token
Produces 字段未定义
| 问题描述 | 可能的修复 |
|---|---|
如果produces未定义全局字段，API 可以返回任何形式的数据。 | 该produces字段需要在架构中定义。 |
解决
swagger: '2.0'
paths: {}
consumes:
- application/json
produces:
- application/json
Produces 字段不包含任何项目
| 问题描述 | 可能的修复 |
|---|---|
如果该produces字段有一个空数组，API 可以默认返回任何类型的数据。 | 全局produces字段需要在数组中至少有一个具有有效 MIME 类型的项目。 |
解决
swagger: '2.0'
paths: {}
produces:
- application/json
...
操作的生产字段不包含任何项目
| 问题描述 | 可能的修复 |
|---|---|
produces操作中没有字段意味着 API 默认可以返回任何类型的数据。 | 任何操作中的字段produces都需要在数组中至少有一项。 |
解决
swagger: '2.0'
paths:
/user/{userId}:
get:
produces:
- application/json
操作不包含 produces 字段
| 问题描述 | 可能的修复 |
|---|---|
如果未定义任何操作的全局produces字段和操作字段，则任何人都可以利用你的 API。produces | produces如果未在全局级别定义，请在操作中定义一个字段。 |
解决
swagger: '2.0'
paths:
/user/{userId}:
get:
produces:
- application/json
...
...
注射
Consumes 字段未定义
| 问题描述 | 可能的修复 |
|---|---|
如果consumes未定义全局字段，API 可以接受任何形式的数据作为输入。这可能会使你的 API 受到任何数量的潜在攻击，例如缓冲区溢出、解码错误或 SQL 注入攻击。 | 该consumes字段需要在架构中定义。 |
解决
swagger: '2.0'
paths: {}
consumes:
- application/json
Consumes 字段不包含任何项目
| 问题描述 | 可能的修复 |
|---|---|
如果该consumes字段有一个空数组，API 可以默认接受任何类型的输入。 | 全局consumes字段需要在数组中至少有一个具有有效 MIME 类型的项目。 |
解决
swagger: '2.0'
paths: {}
consumes:
- application/json
...
操作的 Consumes 字段不包含任何项目
| 问题描述 | 可能的修复 |
|---|---|
consumes操作中没有字段意味着 API 默认可以接受任何类型的输入。 | // operationsconsumes中的字段需要在数组中至少有一项。PUT``PATCH``POST |
解决
swagger: '2.0'
paths:
/user/{userId}:
put:
consumes:
- application/json
操作不包含消耗字段
| 问题描述 | 可能的修复 |
|---|---|
如果全局consumes字段和操作consumes字段（对于PUT/ PATCH/ POST）均未定义，则任何人都可以利用你的 API。 | consumes如果未在全局级别定义，请在操作中定义一个字段。 |
解决
swagger: '2.0'
paths:
/user/{userId}:
put:
consumes:
- application/json
...
...
资产管理不当
OAuth 身份验证使用已弃用的隐式流程
| 问题描述 | 可能的修复 |
|---|---|
| 在 OAuth 隐式流程中，授权服务器在授权请求的响应中发布访问令牌。攻击者可以拦截 API 调用并检索访问令牌以进行其他 API 调用。 | 推荐使用 accessCode 流程。确保 OAuth 身份验证方案未使用隐式流程。 |
解决
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
OAuth 身份验证使用已弃用的密码流程
| 问题描述 | 可能的修复 |
|---|---|
| Oauth 密码授予流程使用用户的凭据来检索访问令牌。攻击者可以拦截 API 调用并检索访问令牌以进行其他 API 调用。 | 推荐使用 accessCode 流程。确保 OAuth 身份验证方案未使用密码流。 |
解决
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
API 信息
此规则类别处理 OpenAPI 信息对象，该对象具有有关 API 的元数据。
信息对象应该有一个描述
| 问题描述 | 可能的修复 |
|---|---|
| 你的 API 定义的 信息对象 没有描述。尽管描述不是必需的，但包含一个描述可以让你向 API 的使用者提供有关 API 的功能和使用方法的信息。这可以是从简短描述到对可能用例的详细解释的任何内容。对于你的组织，在设计阶段定义 API 的描述有助于设置 API 的边界。 | 向 API 定义的信息对象添加描述。 |
解决
swagger: '2.0'
info:
title: An API name
version: '1.0'
description: An API description
信息对象应该有许可证
| 问题描述 | 可能的修复 |
|---|---|
| 你的 API 定义的 info 对象 没有 license object ，这可以帮助你的 API 的使用者了解如何复制和使用 API。 | 将许可证对象添加到 API 定义的信息对象。 |
解决
swagger: '2.0'
info:
title: An API name
version: '1.0'
license:
name: Apache 2.0
url: https://opensource.org/licenses/Apache-2.0
信息对象应该有一个许可证 URL
| 问题描述 | 可能的修复 |
|---|---|
| 你的 API 定义的 许可对象 没有许可 URL，该 URL 提供指向描述许可的网页的链接。尽管不需要许可证 URL，但仅许可证名称可能不足以为你的 API 使用者提供足够的信息，尤其是当你使用自定义许可证时。 | 将 URL 添加到 API 定义的许可对象。 |
解决
swagger: '2.0'
info:
title: An API name
version: '1.0'
license:
name: Apache 2.0
url: https://opensource.org/licenses/Apache-2.0
信息对象应该有服务条款
| 问题描述 | 可能的修复 |
|---|---|
| 你的 API 定义的 信息对象 没有 API 服务条款的 URL。服务条款对于公共 API 通常是强制性的。还建议私有 API 提供指向条款和条件网页的链接。 | 将 API 服务条款的 URL 添加到 API 定义的信息对象中。 |
解决
swagger: '2.0'
info:
title: An API name
version: '1.0'
termsOfService: https://example.com/tos
API 必须有可用的联系信息
| 问题描述 | 可能的修复 |
|---|---|
| 你的 API 定义的 info 对象 没有 contact 对象 ，该对象具有姓名、电子邮件地址或 URL 等联系信息。联系信息为你组织的每个 API 定义指定的所有者。API 的消费者可以直接使用联系人数据，也可以通过 API 门户或目录使用。 | 将联系人对象添加到 API 定义的信息对象。 |
解决
swagger: '2.0'
info:
title: An API name
version: '1.0'
contact:
email: support@example.com
url: https://example.com/support
API 必须有可用的联系人姓名
| 问题描述 | 可能的修复 |
|---|---|
| 你的 API 定义的 联系人对象 没有联系人姓名。尽管联系人姓名不是必需的，但它可以帮助 API 的使用者了解谁拥有 API。它还使你的组织考虑 API 的所有权。 | 将名称添加到 API 定义的联系人对象。 |
解决
swagger: '2.0'
info:
title: An API name
version: '1.0'
contact:
name: A contact name
API 必须有可用的联系 URL 或电子邮件
| 问题描述 | 可能的修复 |
|---|---|
| 你的 API 定义的 联系人对象 没有联系人 URL 或电子邮件地址。尽管联系 URL 或电子邮件不是必需的，但包含其中一个或两者可为你的 API 使用者提供一种联系你的组织或 API 所有者的方式。 | 将联系 URL、电子邮件地址或两者添加到 API 定义的联系对象。 |
解决
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
API 必须有可用的联系电子邮件
| 问题描述 | 可能的修复 |
|---|---|
| 你的 API 定义的 联系人对象 没有电子邮件地址。尽管联系电子邮件不是必需的，但包含电子邮件可以为 API 的使用者提供一种联系你的组织或 API 所有者的方式。 | 将电子邮件地址添加到 API 定义的联系人对象。 |
解决
swagger: '2.0'
info:
title: An API name
version: '1.0'
contact:
email: contact@example.com
API 必须有可用的联系 URL
| 问题描述 | 可能的修复 |
|---|---|
| 你的 API 定义的 联系人对象 没有联系人 URL。尽管联系 URL 不是必需的，但包含一个联系 URL 可为你的 API 的使用者提供一种联系你的组织或 API 所有者的方式。 | 将 URL 添加到 API 定义的联系人对象。 |
解决
swagger: '2.0'
info:
title: An API name
version: '1.0'
contact:
url: https://example.com/support
操作
此规则类别处理 API 路径上的操作。
路径上不应有尾部斜杠
| 问题描述 | 可能的修复 |
|---|---|
API 定义的 路径对象 中的一个或多个 路径项对象 在路径末尾有一个尾部斜杠。某些工具处理以尾部斜杠 ( ) 结尾的路径的方式与处理不带尾部斜杠 ( ) 的路径的方式不同，这可能会导致需要长时间调试的问题。 /path/``/path | 从 API 定义的路径对象中的路径中删除所有尾部斜杠。 |
解决
swagger: '2.0'
# ...
paths:
'/resources':
所有的操作都应该有总结
| 问题描述 | 可能的修复 |
|---|---|
| API 定义中的一个或多个 操作对象 没有摘要。操作的摘要为你的 API 的使用者提供了 HTTP 方法和路径本身不提供的重要上下文。许多组织使用他们在 API 开发过程的定义阶段创建的 API 操作描述作为摘要。 | 为每个操作对象添加摘要。 |
解决
swagger: '2.0'
# ...
paths:
/resources:
get:
summary: A GET operation summary
操作摘要不应以句号结尾
| 问题描述 | 可能的修复 |
|---|---|
API 定义中的一个或多个 操作对象 具有以句点 ( ) 结尾的摘要.。API 文档工具使用摘要作为标题，因此不要以句号结尾。 | 从 API 定义中操作对象级别的所有摘要中删除最后一个句点。 |
解决
swagger: '2.0'
# ...
paths:
/resources:
get:
summary: A GET operation summary
所有操作都应该有描述
| 问题描述 | 可能的修复 |
|---|---|
| API 定义中的一个或多个 操作对象 没有描述。当资源路径、HTTP 方法和摘要没有为 API 的使用者提供足够的上下文时，描述可以为他们提供有关 API 操作及其行为的有用信息。 | 为每个操作对象添加描述。 |
解决
swagger: '2.0'
# ...
paths:
/resources:
get:
description: A GET operation description
所有参数都应该有说明
| 问题描述 | 可能的修复 |
|---|---|
API 定义中操作对象 中的一个或多个 参数对象 没有字段。当 API 名称和上下文没有为 API 的使用者提供足够的信息时，描述可以为他们提供有关参数的有用信息。 description | description为每个参数对象添加一个字段。 |
解决
swagger: '2.0'
# ...
paths:
/resources:
get:
parameters:
- name: status
description: filters resources on their status
in: query
type: string
POST 方法应该有请求体
| 问题描述 | 可能的修复 |
|---|---|
| API 定义中的一个或多个 POST 操作对象 没有请求主体。尽管 HTTP 协议允许没有正文的 POST 请求，但这通常隐藏了设计问题。 | 将请求正文添加到任何 POST 操作对象。 |
解决
swagger: '2.0'
# ...
paths:
/resources:
post:
parameters:
- in: body
name: body
schema:
type: object
PUT 方法应该有请求主体
| 问题描述 | 可能的修复 |
|---|---|
API 定义中的一个或多个 PUT 操作对象 没有请求主体。由于 PUT 操作通常用于替换或创建某些内容，因此没有请求主体可能是错误的。但是，这种用法在某些情况下可能有意义（例如，使用 PUT 链接两个资源，如/resource-ones/id1/other-resources/id2）。 | 将请求正文添加到任何 POST 操作对象。 |
解决
swagger: '2.0'
# ...
paths:
/resources:
put:
parameters:
- in: body
name: body
schema:
type: object
PATCH 方法应该有请求主体
| 问题描述 | 可能的修复 |
|---|---|
| API 定义中的一个或多个 PATCH 操作对象 没有请求主体。由于 PATCH 操作用于进行部分更新，因此 PATCH 方法需要包含请求主体。 | 将请求正文添加到任何 PATCH 操作对象。 |
解决
swagger: '2.0'
# ...
paths:
/resources:
patch:
parameters:
- in: body
name: body
schema:
type: object
所有请求主体都应该有示例
| 问题描述 | 可能的修复 |
|---|---|
| API 定义中一个或多个 正文参数对象中的 模式对象 没有示例。重要的是提供请求正文的示例，以帮助 API 的使用者了解他们将收到哪些数据。它还可以帮助他们生成 模拟服务器 或 集合 。 | example向所有正文参数的架构添加一个字段。 |
解决
swagger: '2.0'
# ...
paths:
/resources:
post:
parameters:
- in: body
name: body
schema:
type: object
example:
aProperty: example value
操作应返回 2xx HTTP 状态代码
| 问题描述 | 可能的修复 |
|---|---|
API 定义中一个或多个 操作对象 的响应 对象 没有类状态代码。操作应成功并返回成功的 HTTP 状态代码。一个操作很少返回不同的代码，例如重定向代码。 2xx``2xx``3xx | 确保所有操作都返回2xx成功状态代码。 |
解决
swagger: '2.0'
# ...
paths:
/resources:
get:
responses:
'200':
description: A success response
操作应返回 5xx HTTP 状态代码
| 问题描述 | 可能的修复 |
|---|---|
API 定义中一个或多个 操作对象 的响应 对象 没有类状态代码。由于操作可能会失败，因此他们需要返回服务器错误 HTTP 状态代码。 5xx``5xx | 确保所有操作都返回5xx状态代码。 |
解决
swagger: '2.0'
# ...
paths:
/resources:
get:
responses:
'500':
description: A server error response
所有回复都应该有例子
| 问题描述 | 可能的修复 |
|---|---|
| API 定义中的一个或多个 响应对象 没有示例。重要的是提供一个响应示例，以帮助 API 的使用者了解他们将收到哪些数据。它还可以帮助他们生成 模拟服务器 或 集合 。 | examples向所有响应对象添加一个字段。 |
解决
swagger: '2.0'
# ...
paths:
/resources:
get:
responses:
'200':
description: A success response
examples:
'application/json':
aProperty: example value
204 响应不能有正文
| 问题描述 | 可能的修复 |
|---|---|
一个或多个 DELETE 操作对象 的响应 对象 有一个 HTTP 状态代码，但也定义了一个响应主体。状态意味着“无内容”，因此不应定义响应主体。 204``204 | 确保带有204状态代码的 DELETE 方法没有响应主体。 |
解决
swagger: '2.0'
#...
paths:
/resources:
delete:
responses:
'204':
description: a success response
楷模
此规则类别处理如何对各种数据类型建模。
架构属性应引用可重用架构
| 问题描述 | 可能的修复 |
|---|---|
一个或多个响应对象 或 正文参数对象 中的架构属性不引用可重用架构。以可重用模式为目标的模式参考 ( $ref)definitions支持设计一致性以及 OpenAPI 文档和 API 文档的可读性，并通过避免模型重复来促进可维护性。 | 将你所有的响应和身体参数模式整合到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
所有可重用的模式都应该有描述
| 问题描述 | 可能的修复 |
|---|---|
定义对象 中的一个或多个 架构对象 没有. 当模式名称和上下文没有为 API 的设计者和消费者提供足够的信息时，描述可以为他们提供有关可重用模式的有用信息。 description | description在你的 API 定义中为每个可重用模式添加一个。 |
解决
swagger: '2.0'
# ...
definitions:
aReusableSchema:
description: a reusable schema description
type: object
所有模式属性都应该有描述
| 问题描述 | 可能的修复 |
|---|---|
API 定义中架构对象 中的一个或多个属性没有description. 当架构名称和上下文无法为 API 的使用者提供足够的信息时，描述可以为他们提供有关元素的有用信息。复杂的描述可能表明 API 的定义或设计中存在问题，因此花时间创建描述可以澄清问题。 | description为架构对象中的每个属性添加一个。 |
解决
swagger: '2.0'
#...
paths:
/resources:
get:
responses:
'200':
description: a success response
schema:
properties:
aProperty:
description: a property description
type: string
数组必须有minItems并maxItems定义
| 问题描述 | 可能的修复 |
|---|---|
API 定义中的一个或多个 架构对象 具有数组类型属性，但未定义minItemor maxItem。消费者和提供者无法处理无限多的元素。设置最小和最大边界有助于定义限制和启用分页。 | 确保 API 定义中具有数组类型的属性已minItem定义maxItem。 |
解决
swagger: '2.0'
# ...
definitions:
anObject:
properties:
aList:
type: array
minItems: 1
maxItems: 100
items:
type: object