Как использовать одно и то же определение для параметра ID и свойства схемы ID?

Question

Мне интересно, есть ли способ в OpenAPI описать, что user_id, используемый в качестве параметра пути, имеет тот же тип значения, что и поле id объекта User.Преимущество этого заключается в повторном использовании описания и примера.

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

Мне не нравится переопределять пример и описание идентификатора пользователя.

Answer 1

Вы можете определить отдельную схему для идентификатора пользователя и задать для параметра / свойства schema ссылку на схему идентификатора пользователя:

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 будут извлекать пример параметра из схемыпример, но описание параметра в настоящее время не выбирается из описания схемы.Не стесняйтесь подать запрос на улучшение .