在OpenAPI的术语中,路径是API公开的端点(例如:/users或/reports/summary/),操作是用来操纵这些路径的HTTP方法(例如:GET、POST或DELETE)。
路径
API的路径和操作在API规范的全局paths分段中进行定义。
paths: /ping: ... /users: ... /users/{id}: ...
所有的路径都是API服务器URL的相对路径。完整的请求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方法的组合定义成一个唯一的操作。这就意味着不允许对同一