Блог

Главная - Вопросы по программированию - Как указать пример двух частей шаблона пути в OpenAPI / Swagger

Как указать пример двух частей шаблона пути в OpenAPI / Swagger

#swagger #openapi

Вопрос:

Задан шаблон пути с двумя частями, такими как:

 paths:
 /blah/{fooPart}-stuff-{barPart}:
    parameters:
      - in: path
        name: fooPart 
        description: foo part of this matrix ID
        required: true
        schema:
          type: string
      - in: path
        name: barPart
        description: bar part of this matrix ID
        required: true
        schema:
          type: string

Я хотел бы привести список примеров. Поскольку fooPart и barPart коррелируют, я хотел бы, чтобы в каждом примере были соответствующие элементы данных. Я бы представил, как помещаю его в компоненты

 examples:
  Happy:
    summary: Happy path
    value:
      fooPart: red
      barPart: up
  Sad:
    summary: Sad path
    value:
      fooPart: up
      barPart: red

Когда я добавляю ссылки в качестве списка примеров к каждому параметру, например так

       - in: path
        name: fooPart 
        description: foo part of this matrix ID
        required: true
        schema:
          type: string
        examples:
          happy:
            $ref: "#/components/example/Happy"
          sad:
            $ref: "#/components/example/Sad"

отображаемый дисплей таков … адекватный? Ошибаешься? Не помогает? Примеры не коррелированы, и массив, указанный в качестве значения, представлен в поле для каждого параметра, как показано здесь. Я признаю, что это то, что я сказал ему сделать. Есть ли какой-нибудь способ объединить все примеры вместе? Или это мой единственный вариант, который я предложу в качестве ответа? Тьфу.

Ответ №1:

Я предполагаю, что единственный вариант-это

 examples:
  HappyFoo:
    summary: Happy path
    value: red
  HappyBar:
    summary: Happy path
    value:  up
  SadFoo:
    summary: Sad path
    value:  red
  SadBar:
    summary: Sad path
    value: red

С каждым параметром, включающим только свои собственные значения, например:

     parameters:
      - in: path
        name: fooPart 
        description: foo part of this matrix ID
        required: true
        schema:
          type: string
        examples:
          Happy:
            $ref: "#/components/examples/HappyFoo"
          Sad:
            $ref: "#/components/examples/SadFoo"

Примеры не коррелированы, но, по крайней мере, значение в поле правильное, как показано здесь.

Комментарии:

1. Верно. В настоящее время (по состоянию на OAS 3.1) мы можем указывать примеры только для отдельных параметров, но не для комбинации параметров. Здесь есть существующий запрос на функцию: github.com/OAI/OpenAPI-Specification/issues/1673

2. Спасибо за указатель и подтверждение моего разочарования.

Метки: