基本结构

OAS 2 此页面适用于 OpenAPI 规范版本 2（前称 Swagger）。要了解最新版本，请访问 OpenAPI 3 页面。

Swagger 定义可以用 JSON 或 YAML 编写。在本指南中，我们只使用 YAML 示例，但 JSON 也可以正常工作。用 YAML 编写的 Swagger 规范示例如下

swagger: "2.0"
info:
  title: Sample API
  description: API description in Markdown.
  version: 1.0.0

host: api.example.com
basePath: /v1
schemes:
  - https

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in Markdown.
      produces:
        - application/json
      responses:
        200:
          description: OK

元数据

每个 Swagger 规范都以 Swagger 版本开头，2.0 是最新版本。Swagger 版本定义了 API 规范的整体结构——您可以记录什么以及如何记录。

swagger: "2.0"

然后，您需要指定 API info——title、description（可选）、version（API 版本，而不是文件修订版或 Swagger 版本）。

info:
  title: Sample API
  description: API description in Markdown.
  version: 1.0.0

version 可以是随机字符串。您可以使用major.minor.patch（如语义版本控制），或任意格式，如1.0-beta 或2016.11.15。description 可以是多行，并支持 GitHub Flavored Markdown 用于富文本表示。info 还支持其他字段，用于联系信息、许可证和其他详细信息。参考： Info 对象。

基本 URL

所有 API 调用的基本 URL 使用 schemes、host 和 basePath 定义

host: api.example.com
basePath: /v1
schemes:
  - https

所有 API 路径相对于基本 URL。例如，/users 实际上是指https://api.example.com/v1/users。更多信息： API 主机和基本 URL。

消耗、生产

consumes 和 produces 部分定义了 API 支持的 MIME 类型。根级别定义可以在各个操作中覆盖。

consumes:
  - application/json
  - application/xml
produces:
  - application/json
  - application/xml

更多信息： MIME 类型。

路径

paths 部分定义了 API 中的各个端点（路径）以及这些端点支持的 HTTP 方法（操作）。例如，GET /users 可以描述为

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in Markdown.
      produces:
        - application/json
      responses:
        200:
          description: OK

更多信息： 路径和操作。

参数

操作可以有参数，这些参数可以通过 URL 路径 (/users/{userId})、查询字符串 (/users?role=admin)、标头 (X-CustomHeader: Value) 和请求主体传递。您可以定义参数类型、格式、是否必需或可选以及其他详细信息

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - in: path
          name: userId
          required: true
          type: integer
          minimum: 1
          description: Parameter description in Markdown.
      responses:
        200:
          description: OK

更多信息： 描述参数。

响应

对于每个操作，您可以定义可能的状态代码，例如 200 OK 或 404 Not Found，以及响应主体的 schema。模式可以在内联定义，也可以通过 $ref 从外部定义引用。您还可以为不同的内容类型提供示例响应。

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - in: path
          name: userId
          required: true
          type: integer
          minimum: 1
          description: The ID of the user to return.
      responses:
        200:
          description: A User object.
          schema:
            type: object
            properties:
              id:
                type: integer
                example: 4
              name:
                type: string
                example: Arthur Dent
        400:
          description: The specified user ID is invalid (e.g. not a number).
        404:
          description: A user with the specified ID was not found.
        default:
          description: Unexpected error

更多信息： 描述响应。

输入和输出模型

全局 definitions 部分允许您定义 API 中使用的常见数据结构。它们可以在需要 schema 时通过 $ref 引用——无论是请求主体还是响应主体。例如，此 JSON 对象

{
  "id": 4,
  "name": "Arthur Dent"
}

可以表示为

definitions:
  User:
    properties:
      id:
        type: integer
      name:
        type: string
    # Both properties are required
    required:  
      - id
      - name

然后在请求主体模式和响应主体模式中引用如下

paths:
  /users/{userId}:
    get:
      summary: Returns a user by ID.
      parameters:
        - in: path
          name: userId
          required: true
          type: integer
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/User'
  /users:
    post:
      summary: Creates a new user.
      parameters:
        - in: body
          name: user
          schema:
            $ref: '#/definitions/User'
      responses:
        200:
          description: OK

身份验证

securityDefinitions 和 security 关键字用于描述 API 中使用的身份验证方法。

securityDefinitions:
  BasicAuth:
    type: basic

security:
  - BasicAuth: []

支持的身份验证方法是

基本身份验证
API 密钥（作为标头或查询参数）
OAuth 2 通用流程（隐式、密码、应用程序和访问代码）

更多信息： 身份验证。

没有找到您要查找的内容？询问社区
发现错误？告诉我们