OAS 3 此页面是关于 OpenAPI 3.0。如果您使用 OpenAPI 2.0，请访问 OpenAPI 2.0 页面。
基本结构
您可以使用 YAML 或 JSON 编写 OpenAPI 定义。在本指南中，我们只使用 YAML 示例，但 JSON 也同样有效。一个用 YAML 编写的 OpenAPI 3.0 定义示例如下所示
openapi: 3.0.0
info:
title: Sample API
description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
version: 0.1.9
servers:
- url: http://api.example.com/v1
description: Optional server description, e.g. Main (production) server
- url: http://staging-api.example.com
description: Optional server description, e.g. Internal staging server for testing
paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in CommonMark or HTML.
responses:
'200': # status code
description: A JSON array of user names
content:
application/json:
schema:
type: array
items:
type: string
所有关键字名称均为 **区分大小写**。
每个 API 定义都必须包含此定义所基于的 OpenAPI 规范的版本
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
info:
title: Sample API
description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
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 还支持其他关键字，用于联系信息、许可证、服务条款和其他详细信息。
参考：Info 对象。
服务器
servers 部分指定 API 服务器和基本 URL。您可以定义一个或多个服务器，例如生产环境和沙盒环境。
servers:
- url: http://api.example.com/v1
description: Optional server description, e.g. Main (production) server
- url: http://staging-api.example.com
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 可以描述为
paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in CommonMark or HTML
responses:
'200':
description: A JSON array of user names
content:
application/json:
schema:
type: array
items:
type: string
操作定义包括参数、请求主体（如果有）、可能的响应状态代码（如 200 OK 或 404 Not Found）和响应内容。有关更多信息，请参阅 路径和操作。
参数
操作可以通过 URL 路径 (/users/{userId})、查询字符串 (/users?role=admin)、标头 (X-CustomHeader: Value) 或 cookie (Cookie: debug=0) 传递参数。您可以定义参数数据类型、格式、是否必需或可选，以及其他详细信息
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- name: userId
in: path
required: true
description: Parameter description in CommonMark or HTML.
schema:
type : integer
format: int64
minimum: 1
responses:
'200':
description: OK
有关更多信息，请参阅 描述参数。
请求主体
如果操作发送请求主体，请使用 requestBody 关键字来描述主体内容和媒体类型。
paths:
/users:
post:
summary: Creates a user.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
responses:
'201':
description: Created
有关更多信息，请参阅 描述请求主体。
响应
对于每个操作，您可以定义可能的 status 代码，例如 200 OK 或 404 Not Found，以及响应主体 schema。模式可以在内联定义，也可以通过 $ref 引用。您还可以为不同的内容类型提供示例响应
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- name: userId
in: path
required: true
description: The ID of the user to return.
schema:
type: integer
format: int64
minimum: 1
responses:
'200':
description: A user object.
content:
application/json:
schema:
type: object
properties:
id:
type: integer
format: int64
example: 4
name:
type: string
example: Jessica Smith
'400':
description: The specified user ID is invalid (not a number).
'404':
description: A user with the specified ID was not found.
default:
description: Unexpected error
请注意，响应 HTTP status 代码必须用引号括起来："200"（OpenAPI 2.0 不需要这样做）。有关更多信息，请参阅 描述响应。
全局 components/schemas 部分允许您定义 API 中使用的通用数据结构。它们可以通过 $ref 引用，无论何时需要 schema——在参数、请求主体和响应主体中。例如，这个 JSON 对象
{
"id": 4,
"name": "Arthur Dent"
}
可以表示为
components:
schemas:
User:
type: object
properties:
id:
type: integer
example: 4
name:
type: string
example: Arthur Dent
# Both properties are required
required:
- id
- name
然后在请求主体模式和响应主体模式中引用，如下所示
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- in: path
name: userId
required: true
schema:
type: integer
format: int64
minimum: 1
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User' # <-------
/users:
post:
summary: Creates a new user.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User' # <-------
responses:
'201':
description: Created
身份验证
securitySchemes 和 security 关键字用于描述 API 中使用的身份验证方法。
components:
securitySchemes:
BasicAuth:
type: http
scheme: basic
security:
- BasicAuth: []
支持的身份验证方法包括
有关更多信息，请参阅 身份验证。
完整规范
完整的 OpenAPI 3.0 规范可在 GitHub 上获得：https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md
没有找到您要找的内容？询问社区
发现错误？告诉我们