如何对 ID 参数和 ID 模式使用相同的定义属性？

Question

我想知道 OpenAPI 中是否有一种方法可以描述用作路径参数的 user_id 与 User 的 id 字段具有相同类型的值目的。这样做的一个好处是重用描述和示例。

openapi: 3.0.1
info:
  title: Test API
  version: 1.0.0
paths:
  /foo/{user_id}:
    get:
      parameters: 
        - $ref: '#/components/parameters/user_id'
      responses:
        '200':
          description: A user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  parameters:
    user_id:
      name: user_id
      in: path
      required: true
      description: the id of a User, from parameters
      example: ghijkl
      schema:
        type: string
  schemas:
    User:
      type: object
      properties:
        id: 
          type: string
          description: the id of a User, from schemas
          example: abcdef

我不喜欢重新定义用户 ID 的示例和描述。

Answer 1

您可以为用户 ID 定义一个单独的架构，并让 parameter/property schema 引用用户 ID 架构：

components:
  parameters:
    user_id:
      name: user_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/UserId'   # <-------
  schemas:
    UserId:
      type: string
      description: The ID of a User
      example: abcdef
    User:
      type: object
      properties:
        id: 
          $ref: '#/components/schemas/UserId' # <-------

Swagger Editor 和 Swagger UI 将从架构示例中获取参数示例，但当前未从架构描述中获取参数说明。欢迎提交 enhancement request.

如何对 ID 参数和 ID 模式使用相同的定义 属性？

How to use the same definition for an ID parameter and an ID schema property?

openapi

如何对 ID 参数和 ID 模式使用相同的定义属性？