OpenAPI 3.0 规则

在定义 API 时，你可以使用 Postman 来识别任何潜在的安全和格式问题。

OpenAPI 3.0 的警告

对于 OpenAPI 3.0 中定义的所有 API，以下列表描述了可能的警告消息和可能的解决方法。

• 损坏的对象级别授权
• securityScheme 声明中未定义安全字段中使用的 OAuth 方案的范围
• 使用的 OAuth 方案的范围未在 securityScheme 声明中定义
• 损坏的用户身份验证
• 未定义安全字段
• 安全字段不包含任何项目
• 安全字段不包含任何方案
• 未定义安全方案对象
• 安全方案对象不包含任何方案
• 安全字段中使用的方案未在安全方案对象中定义
• HTTP 身份验证方案正在使用未知方案
• 操作的安全字段不包含任何项目
• 操作的安全字段不包含任何方案
• 操作不强制执行任何安全方案
• 过多的数据暴露
• API 以纯文本形式接受来自 OAuth 身份验证的凭据
• API 以纯文本形式接受来自 OpenID Connect 身份验证的凭据
• API 以纯文本形式接受来自 OAuth 1.0 身份验证的凭据
• API 接受纯文本形式的 API 密钥
• API 接受纯文本形式的身份验证凭据
• 全局服务器 URL 使用 HTTP 协议
• 操作以纯文本形式接受来自 OAuth 身份验证的凭据
• 操作以纯文本形式接受来自 OpenID Connect 身份验证的凭据
• 操作以纯文本形式接受来自 OAuth 1.0 身份验证的凭据
• 操作接受纯文本形式的 API 密钥
• 操作接受纯文本身份验证凭据
• 操作的服务器 URL 正在使用 HTTP 协议
• 授权 URL 使用 HTTP 协议；凭据将以纯文本形式传输
• Token URL 使用 HTTP 协议
• 刷新 URL 使用 HTTP 协议
• OpenID Connect URL 使用 HTTP 协议
• 资产管理不当
• 使用已弃用的 OAuth 1.0 方案
• OAuth 身份验证使用已弃用的隐式流程
• OAuth 身份验证使用已弃用的密码流程
• API 信息
• 信息对象应该有一个描述
• 信息对象应该有许可证
• 信息对象应该有一个许可证 URL
• 信息对象应该有服务条款
• API 必须有可用的联系信息
• API 必须有可用的联系人姓名
• API 必须有可用的联系 URL 或电子邮件
• API 必须有可用的联系电子邮件
• API 必须有可用的联系 URL
• 操作
• 路径上不应有尾部斜杠
• 所有的操作都应该有总结
• 操作摘要不应以句号结尾
• 所有操作都应该有描述
• 所有参数都应该有说明
• 所有参数都应该有例子
• POST 方法应该有请求体
• PUT 方法应该有请求主体
• PATCH 方法应该有请求主体
• 所有请求主体都应该有示例
• 操作应返回 2xx HTTP 状态代码
• 操作应返回 5xx HTTP 状态代码
• 所有回复都应该有例子
• 204 响应不能有正文
• 楷模
• 架构属性应引用可重用架构
• 所有可重用的模式都应该有描述
• 所有模式属性都应该有描述
• 数组必须有minItems并maxItems定义

securityScheme 声明中未定义安全字段中使用的 OAuth 方案的范围

问题描述	可能的修复
全局安全字段中使用的 OAuth2 范围需要在安全方案字段中定义。否则，攻击者可以引入他们的范围来填补空白并利用系统。	确保使用的所有 OAuth2 范围都在 OAuth2 安全方案中定义。

解决

security:
  - OAuth2:
    - read
    - write
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            read: read objects in your account
            write: write objects to your account

使用的 OAuth 方案的范围未在 securityScheme 声明中定义

问题描述	可能的修复
在操作的安全字段中使用的 OAuth2 范围需要在安全方案字段中定义。否则，攻击者可以引入他们的范围来填补空白并利用系统。	确保使用的所有 OAuth2 范围都在 OAuth2 安全方案中定义。

解决

paths:
  /user:
    get:
      summary: 'Sample endpoint: Returns details about a particular user'
      operationId: listUser
      security:
      - OAuth2:
        - read
        - write
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            read: read objects in your account
            write: write objects to your account

损坏的用户身份验证

未定义安全字段

问题描述	可能的修复
如果未定义全局安全字段，则默认情况下 API 不需要任何身份验证。任何人都可以访问未定义安全字段的 API 操作。	安全字段需要在模式中定义。

解决

openapi: 3.0.0
info:
paths:
security:
    - testAuth : []

安全字段不包含任何项目

问题描述	可能的修复
如果安全字段有一个空数组，默认情况下没有安全方案应用于操作。	安全字段需要在数组中至少有一项。

解决

openapi: 3.0.0
info:
paths:
security:
    - testAuth : []

安全字段不包含任何方案

问题描述	可能的修复
安全字段中的空对象会停用身份验证。如果没有为每个操作定义安全字段，任何人都可以在没有任何身份验证的情况下访问 API 操作。	安全字段数组项不能有空对象。

解决

openapi: 3.0.0
info:
paths:
security:
    - testAuth : []

未定义安全方案对象

问题描述	可能的修复
API 的组件对象没有声明任何可以在 API 的安全字段或单个操作中使用的安全方案。	需要在组件的架构中定义安全方案。

解决

components:
  securitySchemes:
    testAuth:
      type: http
      scheme: basic

安全方案对象不包含任何方案

问题描述	可能的修复
可重用安全方案中的空对象意味着没有为每个操作定义身份验证方案，任何人都可以访问 API 操作而无需任何身份验证。	安全方案需要在对象中至少包含一项。

解决

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

安全字段中使用的方案未在安全方案对象中定义

问题描述	可能的修复
全局或操作安全字段中使用的身份验证方案未在安全方案对象中定义。	安全字段中使用的方案需要在安全方案对象中定义。

解决

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
#...
security:
- BasicAuth: []

HTTP 身份验证方案正在使用未知方案

问题描述	可能的修复
HTTP 身份验证方案的名称必须在 IANA 身份验证方案注册表 中注册。	确保使用在 IANA 身份验证方案注册表中注册的 HTTP 身份验证方案。

解决

servers:
  - url: https://my.server.example.com/
    description: API server
#...
components:
  securitySchemes:
    myAuth:
      type: http
      scheme: basic
#...
security:
  - myAuth: []

操作的安全字段不包含任何项目

问题描述	可能的修复
默认情况下，没有安全方案应用于 API 操作。	任何操作��的安全字段都需要在数组中至少有一项。

解决

openapi: 3.0.0
info:
  title: Example API
  version: '1.0'
paths:
 /user:
  get:
   security:
   - BasicAuth : []
   responses:
    default:
     description: Example
components:
 securitySchemes:
  BasicAuth:
   type: http
   scheme: basic

操作的安全字段不包含任何方案

问题描述	可能的修复
安全字段中的空对象会停用操作的身份验证。任何人都可以访问 API 操作而无需任何身份验证。	在操作中指定至少一项安全要求。

解决

openapi: 3.0.0
info:
  title: Example API
  version: '1.0'
paths:
 /user:
  get:
   security:
   - BasicAuth : []
   responses:
    default:
     description: Example
components:
 securitySchemes:
  BasicAuth:
   type: http
   scheme: basic

操作不强制执行任何安全方案

问题描述	可能的修复
如果全局安全字段和操作的安全字段都没有定义，任何人都可以访问 API 而无需任何身份验证。	在操作中定义一个安全字段。

解决

 openapi: 3.0.0
info:
  title: Example API
  version: '1.0'
paths:
 /user:
  get:
   security:
   - BasicAuth : []
   responses:
    default:
     description: Example
components:
 securitySchemes:
  BasicAuth:
   type: http
   scheme: basic

过多的数据暴露

API 以纯文本形式接受来自 OAuth 身份验证的凭据

问题描述	可能的修复
访问令牌以纯文本形式通过未加密的网络发送。攻击者可以通过监听公共 Wi-Fi 网络中的网络流量来拦截访问令牌。	确保服务器 URL 是有效的 URL 并使用 HTTPS 协议。

解决

servers:
  - url: https://my.api.example.com/
    description: API server
# ...
components:
  securitySchemes:
    OAuth2:
      type: oauth2
# ...
security:
  - OAuth2:
      - write
      - read

API 以纯文本形式接受来自 OpenID Connect 身份验证的凭据

问题描述	可能的修复
凭据以纯文本形式通过未加密的网络发送。攻击者可以通过监听公共 Wi-Fi 网络中的网络流量来拦截访问令牌。	确保服务器 URL 是有效的 URL 并使用 HTTPS 协议。

解决：

components:
 securitySchemes:
  OpenIdScheme:
   type: openIdConnect
   openIdConnectUrl: https://example.com/connect
paths:
 '/pets':
  post:
   operationId: addPet
   servers:
   - url: https://example.com/
     description: API server
   security:
   - OpenIdScheme: []

API 以纯文本形式接受来自 OAuth 1.0 身份验证的凭据

问题描述	可能的修复
身份验证令牌以纯文本形式通过未加密的通道发送。攻击者可以通过监听公共 Wi-Fi 网络中的网络流量来拦截令牌。	确保服务器 URL 是有效的 URL 并使用 HTTPS 协议。

解决

servers:
  - url: https://my.api.example.com/
    description: API server
#...
components:
  securitySchemes:
    OAuth1:
      type: http
      scheme: oauth
#...
security:
  - OAuth1: []

API 接受纯文本形式的 API 密钥

问题描述	可能的修复
API 密钥通过未加密的通道以纯文本形式发送。攻击者可以通过监听公共 Wi-Fi 网络中的网络流量来拦截 API 密钥。	确保服务器 URL 是有效的 URL 并使用 HTTPS 协议。

解决

servers:
  - url: https://my.api.example.com/
    description: API server
#...
components:
  securitySchemes:
    AuthKeyAuth:
      type: apiKey
      name: api-key
      in: header
#...
security:
  - AuthKeyAuth: []

API 接受纯文本形式的身份验证凭据

问题描述	可能的修复
凭据以纯文本形式通过未加密的网络发送。攻击者可以通过监听公共 Wi-Fi 网络中的网络流量来拦截凭据。	确保服务器 URL 是有效的 URL 并使用 HTTPS 协议。

解决

servers:
- url: https://example.com/
  description: Example server
components:
 securitySchemes:
  BasicAuth:
   type: http
   scheme: basic
security:
- BasicAuth: []

全局服务器 URL 使用 HTTP 协议

问题描述	可能的修复
服务器支持未加密的 HTTP 连接，所有请求和响应都将在公开传输。任何在通话过程中监听网络流量的人都可以拦截它们。	确保服务器 URL 是有效的 URL 并使用 HTTPS 协议。

解决

servers:
  - url: https://my.api.example.com/
    description: API server
# ...
components:
  securitySchemes:
    OAuth2:
      type: oauth2
# ...
security:
  - OAuth2:
      - write
      - read

操作以纯文本形式接受来自 OAuth 身份验证的凭据

问题描述	可能的修复
API 操作接受来自流的访问令牌，这些访问令牌通过未加密的通道以纯文本格式传输。攻击者可以拦截 API 调用并检索未加密的令牌。然后他们可以使用令牌进行其他 API 调用。	请确保操作的服务器 URL 是有效的 URL 并使用 HTTPS 协议。

解决

components:
  securitySchemes:
    OAuth2:
      type: oauth2
paths:
  '/pets':
    post:
      operationId: addPet
      servers:
      - url: https://my.api.example.com/
        description: API server

操作以纯文本形式接受来自 OpenID Connect 身份验证的凭据

问题描述	可能的修复
操作的凭据以纯文本形式通过未加密的网络发送。攻击者可以通过监听公共 Wi-Fi 网络中的网络流量来拦截访问令牌。	请确保操作的服务器 URL 是有效的 URL 并使用 HTTPS 协议。

解决

components:
  securitySchemes:
    OpenIdScheme:
      type: openIdConnect
      openIdConnectUrl: https://my.api.openidconnect.example.com/
paths:
  '/pets':
    post:
      operationId: addPet
      servers:
      - url: https://my.api.example.com/
        description: API server

操作以纯文本形式接受来自 OAuth 1.0 身份验证的凭据

问题描述	可能的修复
API 操作接受通过未加密通道以纯文本形式传输的授权令牌。攻击者可以拦截 API 调用并检索未加密的令牌以进行其他 API 调用。	请确保操作的服务器 URL 是有效的 URL 并使用 HTTPS 协议。

解决

paths:
  '/pets':
    post:
      servers:
      - url: https://example.com/
        description: Example server
#...
components:
  securitySchemes:
    OAuth1:
      type: http
      scheme: oauth
#...
security:
  - OAuth1: []

操作接受纯文本形式的 API 密钥

问题描述	可能的修复
API 操作接受通过未加密通道以纯文本格式传输的 API 密钥。攻击者可以拦截 API 调用并检索 API 密钥以进行其他 API 调用。	请确保操作的服务器 URL 是有效的 URL 并使用 HTTPS 协议。

解决

paths:
  '/pets':
    post:
      servers:
      - url: https://example.com/
        description: Example server
# ...
components:
  securitySchemes:
    AuthKeyAuth:
      type: apiKey
      name: api-key
      in: header
# ...
security:
  - AuthKeyAuth: []

操作接受纯文本身份验证凭据

问题描述	可能的修复
API 操作接受通过未加密通道以纯文本格式传输的凭据。攻击者可以拦截 API 调用并检索未加密的令牌。然后他们可以使用令牌进行其他 API 调用。	请确保操作的服务器 URL 是有效的 URL 并使用 HTTPS 协议。

解决

components:
 securitySchemes:
  BasicAuth:
   type: http
   scheme: basic
paths:
 '/pets':
  post:
   operationId: addPet
   servers:
   - url: https://example.com/
     description: Example server
   security:
   - BasicAuth: []

操作的服务器 URL 正在使用 HTTP 协议

问题描述	可能的修复
API 操作支持未加密的 HTTP 连接，所有请求和响应都将公开传输。任何在通话过程中监听网络流量的人都可以拦截它们。	请确保操作的服务器 URL 是有效的 URL 并使用 HTTPS 协议。

解决

get:
  operationId: getPetsById
  servers:
    - url: https://my.api.example.com/

授权 URL 使用 HTTP 协议；凭据将以纯文本形式传输

问题描述	可能的修复
OAuth 授权凭据通过未加密的通道传输。任何在通话过程中监听网络流量的人都可以拦截它们。	请确保授权 URL 是有效的 URL 并遵循 HTTPS 协议。

解决

components:
  securitySchemes:
     OauthScheme:
        type: oauth2
        flows:
          authorizationCode:
            authorizationUrl: https://my.auth.example.com/

Token URL 使用 HTTP 协议

问题描述	可能的修复
OAuth 身份验证令牌通过未加密的通道传输。发送令牌时监听网络流量的任何人都可以拦截它。	确保令牌 URL 是有效的 URL 并遵循 HTTPS 协议。

解决

components:
  securitySchemes:
     OauthScheme:
        type: oauth2
        flows:
          authorizationCode:
            tokenUrl: https://my.token.example.com/

刷新 URL 使用 HTTP 协议

问题描述	可能的修复
OAuth 身份验证刷新令牌通过未加密的通道传输。发送令牌时监听网络流量的任何人都可以拦截它。	确保刷新 URL 是有效的 URL 并遵循 HTTPS 协议。

解决

components:
  securitySchemes:
    OauthFlow:
      type: oauth2
      flows:
        authorizationCode
          authorizationUrl: https://my.auth.example.com/
          tokenUrl: https://my.token.example.com/
          refreshUrl: https://my.refresh.example.com/
          scopes:
            write: modify data
            read: read data

OpenID Connect URL 使用 HTTP 协议

问题描述	可能的修复
OpenID Connect 访问令牌和开放 ID 通过未加密的通道传输。任何在通话过程中监听网络流量的人都可以拦截它们。	确保 openID 连接 URL 是有效的 URL 并遵循 HTTPS 协议。

解决

components:
  securitySchemes:
    OpenIdScheme:
      type: openIdConnect
      openIdConnectUrl: https://example.com/connect
#...
security:
- OpenIdScheme: []

资产管理不当

使用已弃用的 OAuth 1.0 方案

问题描述	可能的修复
安全方案使用 OAuth 1.0 身份验证，该身份验证已被弃用并由 OAuth 2.0 取代。	确保安全方案未使用已弃用的 OAuth 1.0 身份验证。

解决

components:
  securitySchemes:
    OauthFlow:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://my.auth.example.com/
          tokenUrl: https://my.token.example.com/
          scopes:
            write: modify data
            read: read data

OAuth 身份验证使用已弃用的隐式流程

问题描述	可能的修复
在 OAuth 隐式流程中，授权服务器在授权请求的响应中发布��问令牌。攻击者可以拦截 API 调用并检索访问令牌以进行其他 API 调用。	建议使用 authorizationCode 流程。确保 OAuth 身份验证方案未使用隐式流程。

解决

components:
  securitySchemes:
    OauthFlow:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://my.auth.example.com/
          tokenUrl: https://my.token.example.com/
          scopes:
            write: modify data
            read: read data

OAuth 身份验证使用已弃用的密码流程

问题描述	可能的修复
OAuth 密码授予流程使用用户的凭据来检索访问令牌。攻击者可以拦截 API 调用并检索访问令牌以进行其他 API 调用。	建议使用 authorizationCode 流程。确保 OAuth 身份验证方案未使用密码授予流程。

解决

components:
  securitySchemes:
    OauthFlow:
      type: oauth2
      flows:
        authorizationCode:
          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 定义的信息对象添加描述。

解决

openapi: '3.0.3'
info:
  title: An API name
  version: '1.0'
  description: An API description

信息对象应该有许可证

问题描述	可能的修复
你的 API 定义的 info 对象 没有 license object ，这可以帮助你的 API 的使用者了解如何复制和使用 API。	将许可证对象添加到 API 定义的信息对象。

解决

openapi: '3.0.3'
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 定义的许可对象。

解决

openapi: '3.0.3'
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 定义的信息对象中。

解决

openapi: '3.0.3'
info:
  title: An API name
  version: '1.0'
  termsOfService: https://example.com/tos

API 必须有可用的联系信息

问题描述	可能的修复
你的 API 定义的 info 对象 没有 contact 对象 ，该对象具有姓名、电子邮件地址或 URL 等联系信息。联系信息为你组织的每个 API 定义指定的所有者。API 的消费者可以直接使用联系人数据，也可以通过 API 门户或目录使用。	将联系人对象添加到 API 定义的信息对象。

解决

openapi: '3.0.3'
info:
  title: An API name
  version: '1.0'
  contact:
    email: support@example.com
    url: https://example.com/support

API 必须有可用的联系人姓名

问题描述	可能的修复
你的 API 定义的 联系人对象 没有联系人姓名。尽管联系人姓名不是必需的，但它可以帮助 API 的使用者了解谁拥有 API。它还使你的组织考虑 API 的所有权。	将名称添加到 API 定义的联系人对象。

解决

openapi: '3.0.3'
info:
  title: An API name
  version: '1.0'
  contact:
    name: A contact name

API 必须有可用的联系 URL 或电子邮件

问题描述	可能的修复
你的 API 定义的 联系人对象 没有联系人 URL 或电子邮件地址。尽管联系 URL 或电子邮件不是必需的，但包含其中一个或两者可为你的 API 使用者提供一种联系你的组织或 API 所有者的方式。	将联系 URL、电子邮件地址或两者添加到 API 定义的联系对象。

解决

openapi: '3.0.3'
info:
  title: An API name
  version: '1.0'
  contact:
    email: contact@example.com

openapi: '3.0.3'
info:
  title: An API name
  version: '1.0'
  contact:
    url: https://example.com/support

API 必须有可用的联系电子邮件

问题描述	可能的修复
你的 API 定义的 联系人对象 没有电子邮件地址。尽管联系电子邮件不是必需的，但包含电子邮件可以为 API 的使用者提供一种联系你的组织或 API 所有者的方式。	将电子邮件地址添加到 API 定义的联系人对象。

解决

openapi: '3.0.3'
info:
  title: An API name
  version: '1.0'
  contact:
    email: support@example.com

API 必须有可用的联系 URL

问题描述	可能的修复
你的 API 定义的 联系人对象 没有联系人 URL。尽管联系 URL 不是必需的，但包含一个联系 URL 可为你的 API 的使用者提供一种联系你的组织或 API 所有者的方式。	将 URL 添加到 API 定义的联系人对象。

解决

openapi: '3.0.3'
info:
  title: An API name
  version: '1.0'
  contact:
    url: https://example.com/support

操作

此规则类别处理 API 路径上的操作。

路径上不应有尾部斜杠

问题描述	可能的修复
API 定义的 路径对象 中的一个或多个 路径项对象 在路径末尾有一个尾部斜杠。某些工具处理以尾部斜杠 ( ) 结尾的路径的方式与处理不带尾部斜杠 ( ) 的路径的方式不同，这可能会导致需要长时间调试的问题。 /path/``/path	从 API 定义的路径对象中的路径中删除所有尾部斜杠。

解决

openapi: '3.0.3'
# ...
paths:
  '/resources':

所有的操作都应该有总结

问题描述	可能的修复
API 定义中的一个或多个 操作对象 没有摘要。操作的摘要为你的 API 的使用者提供了 HTTP 方法和路径本身不提供的重要上下文。许多组织使用他们在 API 开发过程的定义阶段创建的 API 操作描述作为摘要。	为每个操作对象添加摘要。

解决

openapi: '3.0.3'
# ...
paths:
  /resources:
    get:
      summary: A GET operation summary

操作摘要不应以句号结尾

问题描述	可能的修复
API 定义中的一个或多个 操作对象 具有以句点 ( ) 结尾的摘要.。API 文档工具使用摘要作为标题，因此不应以句号结尾。	从 API 定义中操作对象级别的所有摘要中删除最后一个句点。

解决

openapi: '3.0.3'
# ...
paths:
  /resources:
    get:
      summary: A GET operation summary

所有操作都应该有描述

问题描述	可能的修复
API 定义中的一个或多个 操作对象 没有描述。当资源路径、HTTP 方法和摘要没有为 API 的使用者提供足够的上下文时，描述可以为他们提供有关 API 操作及其行为的有用信息。	为每个操作对象添加描述。

解决

openapi: '3.0.3'
# ...
paths:
  /resources:
    get:
      description: A GET operation description

所有参数都应该有说明

问题描述	可能的修复
API 定义中操作对象 中的一个或多个 参数对象 没有字段。当 API 名称和上下文没有为 API 的使用者提供足够的信息时，描述可以为他们提供有关参数的有用信息。 description	description为每个参数对象添加一个字段。

解决

openapi: '3.0.3'
# ...
paths:
  /resources:
    get:
      parameters:
        - name: status
          description: Filters resources on their status
          in: query
          schema:
            type: string

所有参数都应该有例子

问题描述	可能的修复
API 定义中操作对象 中的一个或多个 参数对象 没有 or 字段。提供未记录的示例（使用属性）或记录的示例（使用属性）以帮助 API 的使用者了解要提供的数据非常重要。它还可以帮助他们生成 模拟服务器 或 集合 。 example``examples``example``examples	添加一个exampleorexamples字段，为 API 的使用者提供参数潜在值的示例。

解决

openapi: '3.0.3'
# ...
paths:
  /resources:
    get:
      parameters:
        - name: status
          description: Filters resources on their status
          in: query
          example: done
          schema:
            type: string

openapi: '3.0.3'
# ...
paths:
  /resources:
    get:
      parameters:
        - name: status
          description: Filters resources on their status
          in: query
          examples:
            anExample:
              summary: An example
              description: A description of an example
              value: done
          schema:
            type: string

POST 方法应该有请求体

问题描述	可能的修复
API 定义中的一个或多个 POST 操作对象 没有 请求主体对象 。尽管 HTTP 协议允许没有正文的 POST 请求，但这通常隐藏了设计问题。	将请求主体对象添加到任何 POST 操作对象。

解决

openapi: '3.0.3'
# ...
paths:
  /resources:
    post:
      requestBody:
        content:
          'application/json':
            schema:
              type: object

PUT 方法应该有请求主体

问题描述	可能的修复
API 定义中的一个或多个 PUT 操作对象 没有 请求主体对象 。由于 PUT 操作通常用于替换或创建某些内容，因此没有请求主体可能是错误的。但是，这种用法在某些情况下可能有意义（例如，使用 PUT 链接两个资源，如/resource-ones/id1/other-resources/id2）。	将请求主体对象添加到任何 POST 操作对象。

解决

openapi: '3.0.3'
# ...
paths:
  /resources:
    put:
      requestBody:
        content:
          'application/json':
            schema:
              type: object

PATCH 方法应该有请求主体

问题描述	可能的修复
API 定义中的一个或多个 PATCH 操作对象 没有 请求主体对象 。由于 PATCH 操作用于进行部分更新，因此 PATCH 方法需要包含请求主体。	将请求主体对象添加到任何 PATCH 操作对象。

解决

openapi: '3.0.3'
# ...
paths:
  /resources:
    patch:
      requestBody:
        content:
          'application/json':
            schema:
              type: object

所有请求主体都应该有示例

问题描述	可能的修复
API 定义中的一个或多个 请求主体对象 没有示例。重要的是提供未记录的示例（使用属性example）或记录的示例（使用属性examples）以帮助你的 API 的使用者了解他们将收到哪些数据。它还可以帮助他们生成 模拟服务器 或 集合 。	向所有请求正文对象添加一个example或字段。examples

解决

openapi: '3.0.3'
# ...
paths:
  /resources:
    post:
      requestBody:
        content:
          'application/json':
            schema:
              # ...
            example:
              aProperty: example value

openapi: '3.0.3'
# ...
paths:
  /resources:
    post:
      requestBody:
        content:
          'application/json':
            schema:
              # ...
            examples:
              anExample:
                summary: An example
                description: This is an example description
                value:
                  aProperty: example value

操作应返回 2xx HTTP 状态代码

问题描述	可能的修复
API 定义中一个或多个 操作对象 的响应 对象 没有类状态代码。操作应成功并返回成功的 HTTP 状态代码。一个操作很少返回不同的代码，例如重定向代码。 2xx``2xx``3xx	确保操作返回2xx成功状态代码。

解决

openapi: '3.0.3'
# ...
paths:
  /resources:
    get:
      responses:
        '200':
          description: A success response

操作应返回 5xx HTTP 状态代码

问题描述	可能的修复
API 定义中一个或多个 操作对象 的响应 对象 没有类状态代码。由于操作可能会失败，因此他们需要返回服务器错误 HTTP 状态代码。 5xx``5xx	确保所有操作都返回5xx状态代码。

解决

openapi: '3.0.3'
# ...
paths:
  /resources:
    get:
      responses:
        '500':
          description: A server error response

所有回复都应该有例子

问题描述	可能的修复
API 定义中的一个或多个 响应对象 没有示例。重要的是提供未记录的示例（使用属性example）或记录的示例（使用属性examples）以帮助你的 API 的使用者了解他们将收到哪些数据。它还可以帮助他们生成 模拟服务器 或 集合 。	向所有响应对象添加一个example或字段。examples

解决

openapi: '3.0.3'
# ...
paths:
  /resources:
    get:
      responses:
        '200':
          description: A success response
          content:
            'application/json':
              schema:
                # ...
              example:
                aProperty: example

openapi: '3.0.3'
# ...
paths:
  /resources:
    get:
      responses:
        '200':
          description: A success response
          content:
            'application/json':
              schema:
                # ...
              examples:
                anExample:
                  summary: An example
                  description: This is an example description
                  value:
                    aProperty: example value

204 响应不能有正文

问题描述	可能的修复
一个或多个 DELETE 操作对象 的响应 对象 有一个 HTTP 状态代码，但也定义了一个响应主体。状态意味着“无内容”，因此不应定义响应主体。 204``204	确保带有204状态代码的 DELETE 方法没有响应主体。

解决

openapi: '3.0.3'
#...
paths:
  /resources:
    delete:
      responses:
        '204':
          description: a success response

楷模

此规则类别处理如何对各种数据类型建模。

架构属性应引用可重用架构

问题描述	可能的修复
一个或多个响应对象 或 正文参数对象 中的架构属性不引用可重用架构。以可重用模式为目标的模式参考 ( $ref)definitions支持设计一致性以及 OpenAPI 文档和 API 文档的可读性，并通过避免模型重复来促进可维护性。	将你所有的响应和身体参数模式整合到definitions.

解决

openapi: '3.0.3'
# ...
paths:
  /resources:
    get:
      responses:
        '200':
          description: a success response
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/Resources'
components:
  schemas:
    Resources:
      type: object

所有可重用的模式都应该有描述

问题描述	可能的修复
组件对象 中的一个或多个 架构对象 没有. 当模式名称和上下文没有为 API 的设计者和消费者提供足够的信息时，描述可以为他们提供有关可重用模式的有用信息。 description	description在你的 API 定义中为每个可重用模式添加一个。

解决

openapi: '3.0.3'
# ...
components:
  schemas:
    aReusableSchema:
      description: A reusable schema description
      type: object

所有模式属性都应该有描述

问题描述	可能的修复
API 定义中架构对象 中的一个或多个属性没有description. 当架构名称和上下文无法为 API 的使用者提供足够的信息时，描述可以为他们提供有关元素的有用信息。复杂的描述可能表明 API 的定义或设计中存在问题，因此花时间创建描述可以澄清问题。	description为架构对象中的每个属性添加一个。

解决

openapi: '3.0.3'
# ...
paths:
  /resources:
    get:
      responses:
        '200':
          description: A success response
          content:
            'application/json':
              schema:
                properties:
                  aProperty:
                    description: A property description
                    type: string

数组必须有minItems并maxItems定义

问题描述	可能的修复
API 定义中的一个或多个 架构对象 具有数组类型属性，但未定义minItemor maxItem。消费者和提供者无法处理无限多的元素。设置最小和最大边界有助于定义限制和启用分页。	确保 API 定义中具有数组类型的属性已minItem定义maxItem。

解决

openapi: '3.0.3'
# ...
components:
  schemas:
    anObject:
      properties:
        aList:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: object