跳过内容

路径和操作

在 OpenAPI 术语中，路径（paths）是您的 API 暴露的端点（资源），例如 /users 或 /reports/summary/；而**操作（operations）**是用于操作这些路径的 HTTP 方法，例如 GET、POST 或 DELETE。

路径

API 路径和操作在 API 规范的全局 paths 部分中定义。

1
paths:
2
  /ping: ...
3
  /users: ...
4
  /users/{id}: ...

所有路径都相对于 API 服务器 URL。完整的请求 URL 构造为 <server-url>/path。全局 servers 也可以在路径级别或操作级别覆盖（更多信息请参见下文）。路径可以有一个可选的简短 summary 和一个较长的 description 用于文档目的。此信息应与此路径中的所有操作相关。description 可以是多行的，并且支持 Markdown (CommonMark) 用于富文本表示。

1
paths:
2
  /users/{id}:
3
    summary: Represents a user
4
    description: >
5
      This resource represents an individual user in the system.
6
      Each user is identified by a numeric `id`.
7


8
    get: ...
9
    patch: ...
10
    delete: ...

路径模板

您可以使用大括号 {} 将 URL 的某些部分标记为路径参数

1
/users/{id}
2
/organizations/{orgId}/members/{memberId}
3
/report.{format}

API 客户端在进行 API 调用时需要提供适当的参数值，例如 /users/5 或 /users/12。

操作

对于每个路径，您可以定义用于访问该路径的操作（HTTP 方法）。OpenAPI 3.0 支持 get、post、put、patch、delete、head、options 和 trace。单个路径可以支持多个操作，例如 GET /users 用于获取用户列表，POST /users 用于添加新用户。OpenAPI 将唯一操作定义为路径和 HTTP 方法的组合。这意味着同一路径的两个 GET 或两个 POST 方法是不允许的——即使它们具有不同的参数（参数不影响唯一性）。下面是一个操作的最小示例

1
paths:
2
  /ping:
3
    get:
4
      responses:
5
        "200":
6
          description: OK

这是一个包含参数和响应模式的更详细示例

1
paths:
2
  /users/{id}:
3
    get:
4
      tags:
5
        - Users
6
      summary: Gets a user by ID.
7
      description: >
8
        A detailed description of the operation.
9
        Use markdown for rich text representation,
10
        such as **bold**, *italic*, and [links](https://swagger.org.cn).
11
      operationId: getUserById
12
      parameters:
13
        - name: id
14
          in: path
15
          description: User ID
16
          required: true
17
          schema:
18
            type: integer
19
            format: int64
20
      responses:
21
        "200":
22
          description: Successful operation
23
          content:
24
            application/json:
25
              schema:
26
                $ref: "#/components/schemas/User"
27
      externalDocs:
28
        description: Learn more about user operations provided by this API.
29
        url: http://api.example.com/docs/user-operations/
30


31
components:
32
  schemas:
33
    User:
34
      type: object
35
      properties:
36
        id:
37
          type: integer
38
          format: int64
39
        name:
40
          type: string
41
      required:
42
        - id
43
        - name

操作还支持一些用于文档目的的可选元素

  • 一个简短的 summary 和一个较长的 description，描述操作的功能。description 可以是多行的，并且支持 Markdown (CommonMark) 用于富文本表示。
  • tags – 用于按资源或任何其他限定符对操作进行逻辑分组。请参见使用标签分组操作。
  • externalDocs – 用于引用包含额外文档的外部资源。

操作参数

OpenAPI 3.0 支持通过路径、查询字符串、请求头和 Cookie 传递的操作参数。您还可以为向服务器传输数据的操作（如 POST、PUT 和 PATCH）定义请求体。有关详细信息，请参阅描述参数和描述请求体。

路径中的查询字符串

查询字符串参数**不得**包含在路径中。它们应该定义为查询参数。

不正确

1
paths:
2
  /users?role={role}:

正确

1
paths:
2
  /users:
3
    get:
4
      parameters:
5
        - in: query
6
          name: role
7
          schema:
8
            type: string
9
            enum: [user, poweruser, admin]
10
          required: true

这也意味着不可能有仅在查询字符串上有所不同的多个路径，例如

1
GET /users?firstName=value&lastName=value
2
GET /users?role=value

这是因为 OpenAPI 将唯一操作视为路径和 HTTP 方法的组合，而额外的参数不会使操作变得唯一。因此，您应该使用唯一的路径，例如

1
GET /users/findByName?firstName=value&lastName=value
2
GET /users/findByRole?role=value

operationId

operationId 是一个可选的唯一字符串，用于标识操作。如果提供，这些 ID 在您的 API 中描述的所有操作中必须是唯一的。

1
/users:
2
  get:
3
    operationId: getUsers
4
    summary: Gets all users
5
    ...
6
  post:
7
    operationId: addUser
8
    summary: Adds a new user
9
    ...
10
/user/{id}:
11
  get:
12
    operationId: getUserById
13
    summary: Gets a user by user ID
14
    ...

operationId 的常见用例包括

  • 一些代码生成器使用此值来命名代码中相应的方法。
  • 链接可以通过 operationId 引用链接的操作。

已弃用的操作

您可以将特定操作标记为 deprecated，以表明它们应该逐步停止使用

1
/pet/findByTags:
2
  get:
3
    deprecated: true

工具可能会以特定方式处理已弃用的操作。例如，Swagger UI 会以不同的样式显示它们

Deprecated operation in Swagger UI

覆盖全局服务器

全局 servers 数组可以在路径级别或操作级别进行覆盖。如果某些端点使用与 API 其余部分不同的服务器或基础路径，这将非常有用。常见示例如下

  • 文件上传和下载操作使用不同的基础 URL。

  • 已弃用但仍可用的端点。

    服务器

1
paths:
2
  /files:
3
    description: File upload and download operations
4
    servers:
5
      - url: https://files.example.com
6
        description: Override base path for all operations with the /files path
7
    ...
8


9
/ping:
10
    get:
11
      servers:
12
        - url: https://echo.example.com
13
          description: Override base path for the GET /ping operation

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

© . All rights reserved.