鲁达 在OpenAPI的术语中，路径是API公开的端点（例如：/users或/reports/summary/），操作是用来操纵这些路径的HTTP方法（例如：GET、POST或DELETE）。
路径
API的路径和操作在API规范的全局paths分段中进行定义。
paths: /ping: ... /users: ... /users/{id}: ...所有的路径都是API服务器URL的相对路径。完整的请求URL被构造成<server-url>/path的形式。全局的servers也可以在路径级别或操作级别上覆盖（更多内容见下文）。路径可以有一段可选的简短summary和一段较长的的description，用作路径的文档。这些信息应该和这个路径中的所有操作相关。description可以是多行的，并且支持Markdown（CommonMark），以便于进行富文本表示。
路径模板
你可以使用花括号{ }，将URL的一部分标记为路径参数：
/users/{id} /organizations/{orgId}/members/{memberId} /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方法 — 即使它们具有不同的参数（参数对于唯一性没有影响）。以下是操作的最小示例：
paths: /ping: get: responses: '200': description: OK以下是参数和响应模式的更详细的示例：
paths: /users/{id}: get: tags: - Users summary: Gets a user by ID. description: > A detailed description of the operation. Use markdown for rich text representation, such as **bold**, *italic*, and [links](https://swagger.io). operationId: getUserById parameters: - name: id in: path description: User ID required: true schema: type: integer format: int64 responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/User' externalDocs: description: Learn more about user operations provided by this API. url: components: schemas: User: type: object properties: id: type: integer format: int64 name: type: string required: - id - name操作还支持一些可选的元素，用来编写文档：
- 一段简短的summary和一段较长的description，用来说明操作的用途。description可以是多行的，并且支持Markdown（CommonMark），以便于进行富文本表示。
- tags — 用来按照资源或任何其他限定符对操作进行分组。请参考“使用标签分组操作”。
- externalDocs — 用来引用包含其他文档的外部资源。
操作参数
OpenAPI 3.0支持通过路径、查询字符串、标头和cookies传递操作参数。你还可以为将数据传输到服务器的操作定义请求主体，例如：POST、PUT和PATCH。有关的详细信息，请参考“描述参数”和“描述请求体”。
路径中的查询字符串
查询字符串参数不得包含在路径中。它们应该被定义为查询参数。以下是不正确的示例：
paths: /users?role={role}:以下是正确的示例：
paths: /users: get: parameters: - in: query name: role schema: type: string enum: [user, poweruser, admin] required: true这也意味着不可能有多个路径只在查询字符串中有所不同，例如：
GET /users?firstName=value&lastName=value GET /users?role=value这是因为OpenAPI将一个唯一的操作视为一个路径和一个HTTP方法的组合，而其他参数不能确保操作的唯一性。相反，你应该使用唯一的路径，例如：
GET /users/findByName?firstName=value&lastName=value GET /users/findByRole?role=valueoperationId
operationId是一个可选的唯一字符串，用来标识一个操作。如果提供的话，这些ID在API中描述的所有操作中必须是唯一的。
/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 ...operationId的一些常见用例，如下所示：
- 某些代码生成器会使用该值来命名代码中的相应方法。
- 链接可以通过operationId来引用链接的操作。
废弃的方法
你可以将特定的操作标记成已废弃，表示这些操作应该逐渐被停用。
/pet/findByTags: get: deprecated: true工具可能会以特定的方式来处理已废弃的操作。例如，Swagger UI会以不同的样式来显示已废弃的操作：
覆盖全局服务器
你可以在路径级别或操作级别覆盖全局的servers数组。如果某些端点使用的服务器或基础路径与API的其他部分有所不同，那么这个选项非常有用。常见用例，如下所示：
- 文件上传和下载操作使用不同的基础URL。
- 已废弃，但功能仍然有效的端点。