您的位置 首页 > 数码极客

如何prefab中的资源进行引用转路径

在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=value

operationId

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。
  • 已废弃,但功能仍然有效的端点。
servers: - url: paths: /files: description: File upload and download operations servers: - url: description: Override base path for all operations with the /files path ... /ping: get: servers: - url: description: Override base path for the GET /ping operation

责任编辑: 鲁达

1.内容基于多重复合算法人工智能语言模型创作,旨在以深度学习研究为目的传播信息知识,内容观点与本网站无关,反馈举报请
2.仅供读者参考,本网站未对该内容进行证实,对其原创性、真实性、完整性、及时性不作任何保证;
3.本站属于非营利性站点无毒无广告,请读者放心使用!

“如何prefab中的资源进行引用转路径”边界阅读