Как правильно подойти к вопросу: возможно ли в swagger сгенерировать условную схему?

Ссылка скопирована
Swagger
1 ответ

Допустим есть два тела запроса в typescript 

type TBody = { type: 'action1' payload: { value: number action: string } } | { type: 'action2' payload: null }

По вводным: возможно ли такое тело запроса например для post описать в swagger чтобы на основе json-схемы генерировать запросы? Чтобы в свагере можно было отправлять данные в зависимости от поля.

По вводным: тоже самое и для ответа запроса например get. Можно ли описать данные которые возвращаются в зависимости от какого-то поля.

По вводным: было бы неплохо если такое возможно показать пример фоткой как это выглядит в свагере

Нужно решить такую задачу?

Опишите проблему, и специалист поможет с настройкой, исправлением ошибки или доработкой сайта. Подберём понятный план работ без лишней переписки.

Заказать помощь
Лучший ответ
1
Редакция Security Ответ

Да, в Swagger/OpenAPI можно описать условную схему тела запроса или ответа, где структура зависит от значения поля. Для такого случая используются oneOf, anyOf и discriminator. В вашем примере правильнее всего описывать union по полю type: если type = action1, payload объект; если type = action2, payload равен null.

Пример для OpenAPI 3:

components:
  schemas:
    Action1Body:
      type: object
      required: [type, payload]
      properties:
        type:
          type: string
          enum: [action1]
        payload:
          type: object
          required: [value, action]
          properties:
            value:
              type: number
            action:
              type: string

    Action2Body:
      type: object
      required: [type, payload]
      properties:
        type:
          type: string
          enum: [action2]
        payload:
          nullable: true

    RequestBody:
      oneOf:
        - $ref: '#/components/schemas/Action1Body'
        - $ref: '#/components/schemas/Action2Body'
      discriminator:
        propertyName: type

components: schemas: Action1Body: type: object required: [type, payload] properties: type: type: string enum: [action1] payload: type: object required: [value, action] properties: value: type: number action: type: string Action2Body: type: object required: [type, payload] properties: type: type: string enum: [action2] payload: nullable: true RequestBody: oneOf: - $ref: '#/components/schemas/Action1Body' - $ref: '#/components/schemas/Action2Body' discriminator: propertyName: type

В endpoint это подключается так:

paths:
  /actions:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBody'

paths: /actions: post: requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RequestBody'

В Swagger UI это обычно отображается как выбор одного из вариантов схемы. Пользователь может переключать вариант тела запроса и видеть разные поля для каждого типа. Для ответов логика такая же: указываете oneOf в schema ответа.

Если вы генерируете OpenAPI из TypeScript, проверьте поддержку union/discriminator в вашем генераторе. Не все инструменты корректно превращают TypeScript union в OpenAPI. Иногда приходится явно описывать DTO-классы и указывать oneOf вручную через декораторы или расширение схемы.

Итог: да, условная схема описывается через oneOf и discriminator. Главное — чтобы каждый вариант имел различимое поле type с enum/const-значением, иначе Swagger UI и валидаторы не смогут однозначно выбрать нужную ветку.

Другие ответы (0)

Пока нет других ответов. Будьте первым, кто поможет автору.

Ответить на вопрос

комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

Вам также может быть интересно

VPN Как правильно настроить vless для Android TV? 1 ответ Pyrogram Как правильно зарегистрировать юзер бота в Telegram? 1 ответ печатные-платы Как заставить запускаться программу M3.exe от компании Hanxing AOI в инспекционной машине на Windows 7 Pro? 1 ответ 1С Как выдать дефолтному пользователю 1С 8.3 право на загрузку XML? 1 ответ