跳转到内容

路径和操作

在 OpenAPI 术语中，路径 是您的 API 公开的端点（资源），例如 /users 或 /reports/summary/，而 操作 是用于操作这些路径的 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。

  • 已弃用但仍然可以使用的端点。

    servers

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

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

Swagger 开源
Swagger
专业工具
资源