基本结构

您可以使用 YAML 或 JSON 编写 OpenAPI 定义。在本指南中，我们仅使用 YAML 示例，但 JSON 的效果也一样。用 YAML 编写的示例 OpenAPI 3.0 定义如下所示

1
openapi: 3.0.0
2
info:
3
  title: Sample API
4
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
5
  version: 0.1.9
6

7
servers:
8
  - url: http://api.example.com/v1
9
    description: Optional server description, e.g. Main (production) server
10
  - url: http://staging-api.example.com
11
    description: Optional server description, e.g. Internal staging server for testing
12

13
paths:
14
  /users:
15
    get:
16
      summary: Returns a list of users.
17
      description: Optional extended description in CommonMark or HTML.
18
      responses:
19
        "200": # status code
20
          description: A JSON array of user names
21
          content:
22
            application/json:
23
              schema:
24
                type: array
25
                items:
26
                  type: string

所有关键字名称都区分大小写。

元数据

每个 API 定义都必须包括此定义所基于的 OpenAPI 规范的版本

1
openapi: 3.0.0

OpenAPI 版本定义了 API 定义的整体结构 – 您可以记录什么以及如何记录。OpenAPI 3.0 使用带有三部分版本号的语义版本控制。可用版本为 3.0.0、3.0.1、3.0.2 和 3.0.3；它们在功能上是相同的。

info 部分包含 API 信息：title、description（可选）、version

1
info:
2
  title: Sample API
3
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
4
  version: 0.1.9

title 是您的 API 名称。description 是有关您 API 的扩展信息。它可以是多行，并支持 CommonMark Markdown 方言以进行富文本表示。HTML 支持的程度由 CommonMark 提供（请参阅 CommonMark 0.27 规范中的 HTML 代码块）。version 是一个任意字符串，用于指定您的 API 版本（不要将其与文件修订或 openapi 版本混淆）。您可以使用语义版本控制，如 major.minor.patch，或使用任意字符串，如 1.0-beta 或 2017-07-25。info 还支持用于联系信息、许可证、服务条款和其他详细信息的其他关键字。

参考：信息对象。

服务器

servers 部分指定 API 服务器和基本 URL。您可以定义一个或多个服务器，例如生产环境和沙盒环境。

1
servers:
2
  - url: http://api.example.com/v1
3
    description: Optional server description, e.g. Main (production) server
4
  - url: http://staging-api.example.com
5
    description: Optional server description, e.g. Internal staging server for testing

所有 API 路径都相对于服务器 URL。在上面的示例中，/users 表示 http://api.example.com/v1/users 或 http://staging-api.example.com/users，具体取决于所使用的服务器。有关更多信息，请参阅 API 服务器和基本路径。

路径

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

1
paths:
2
  /users:
3
    get:
4
      summary: Returns a list of users.
5
      description: Optional extended description in CommonMark or HTML
6
      responses:
7
        "200":
8
          description: A JSON array of user names
9
          content:
10
            application/json:
11
              schema:
12
                type: array
13
                items:
14
                  type: string