路径和操作

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

在 Swagger 术语中，路径是您的 API 公开的端点（资源），例如 /users 或 /reports/summary，而操作是用于操作这些路径的 HTTP 方法，例如 GET、POST 或 DELETE。

路径

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

paths:
  /ping:
    ...
  /users:
    ...
  /users/{id}:
    ...

所有路径相对于 basePath（请参阅 API 主机和基本 URL）。完整的请求 URL 构建为 scheme://host/basePath/path。

路径模板

Swagger 支持路径模板，这意味着您可以使用花括号 {} 来标记 URL 中作为路径参数的部分

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

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

操作

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

paths:
  /ping:
    get:
      responses:
        200:
          description: OK

包含参数和响应模式的更详细示例

paths:
  /users/{id}:
    get:
      summary: Gets a user by ID.
      description: >
        A detailed description of the operation.
        GitHub Flavored Markdown can be used for rich text representation,
        such as **bold**, *italic* and [links](https://swagger.org.cn).
      operationId: getUsers
      tags:
        - users
      produces:
        - application/json
        - application/xml
      parameters:
        - name: id
          in: path
          description: User ID
          type: integer
          required: true
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/User'
      externalDocs:
        url: http://api.example.com/docs/user-operations/
        description: Learn more about User operations provided by this API.
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
    required:
      - id
      - name

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

简短的 summary 和较长的 description，描述操作的作用。description 可以是多行并且支持 GitHub Flavored Markdown 以实现富文本表示。
tags 用于在 Swagger UI 中对操作进行分组。
externalDocs 允许引用包含附加文档的外部资源。

操作参数

Swagger 支持通过路径、查询字符串、标头和请求主体传递的操作参数。有关详细信息，请参阅描述参数。

operationId

每个操作都可以指定唯一的 operationId。一些代码生成器使用此值来命名代码中的相应方法。

  /users:
     get:
       operationId: getUsers
       summary: Gets all users.
       ...
     post:
       operationId: addUser
       summary: Adds a new user.
       ...
   /user/{id}:
     get:
       operationId: getUserById
       summary: Gets a user by user ID.
       ...

路径中的查询字符串

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

paths:
  /users?role={role}:

正确的

paths:
  /users:
    get:
      parameters:
        - in: query
          name: role
          type: string
          enum: [user, poweruser, admin]
          required: false

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

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

这是因为 Swagger 将唯一操作视为路径和 HTTP 方法的组合，而附加参数不会使操作变得唯一。相反，您应该使用唯一的路径，例如

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

标记为已弃用

您可以将特定操作标记为 deprecated 以指示应将其从使用中过渡

  /pet/findByTags:
    get:
      deprecated: true

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

Deprecated operation in Swagger UI

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