如何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