Как определить перечисление в OpenAPI (Swagger)?

ProgramBox

Как определить перечисление в OpenAPI (Swagger)?

Post author:admin
Запись опубликована:20 января, 2022
Post category:Вопросы по программированию

#swagger #openapi

Вопрос:

Кто-нибудь знает, как определить возможные значения «перечисления» в определении OpenAPI 2.0, чтобы они отображались на вкладке Модель пользовательского интерфейса Swagger? Пример здесь: https://petstore.swagger.io/#!/pet/addPet имеет опцию перечисления для status свойства. Как определить такое перечисление в OpenAPI 2.0?

Ответ №1:

«перечисление» работает так в OpenAPI 2.0:

       {
        "in": "query",
        "name": "sample",
        "description": "a sample parameter with an enum value",
        "type": "string",
        "enum": [ "1", "2"],
        "required": true
      }

и в OpenAPI 3.0:

       {
        "in": "query",
        "name": "sample",
        "description": "a sample parameter with an enum value",
        "schema": {
          "type": "string",
          "enum": [ "1", "2"]
        },
        "required": true
      }

Как вы можете видеть, существует параметр запроса sample типа string, который содержит перечисление с указанием двух возможных значений. В этом случае в примере указано, что параметр является обязательным, поэтому пользовательский интерфейс не будет отображать пустое значение в качестве опции.

Для минимального рабочего образца попробуйте это:

 {
  "swagger": "2.0",
  "info": {
    "title": "title",
    "description": "descriptor",
    "version": "0.1"
  },
  "paths": {
    "/sample": {
      "post": {
        "description": "sample",
        "parameters": [
          {
            "in": "query",
            "name": "sample",
            "description": "a sample parameter with an enum value",
            "type": "string",
            "enum": [
              "1",
              "2"
            ],
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "Successful request."
          }
        }
      }
    }
  }
}

Чтобы протестировать его локально, вы можете объявить переменную (например spec ) в своем javascript и передать ее в объект SwaggerUI.

   var spec = { ... };

  window.swaggerUi = new SwaggerUi({
    url: url,
    spec: spec,
    dom_id: "swagger-ui-container",
    supportedSubmitMethods: ['get', 'post', 'put', 'delete'],
    onComplete: function(swaggerApi, swaggerUi){
    ...

В url этом случае параметр будет проигнорирован.

В конечном итоге результат выглядит следующим образом:

введите описание изображения здесь

1. Привет, веброн. Спасибо за ваше предложение. По-прежнему никакой радости от этого… Независимо от того, что я пытаюсь, я все равно не могу получить такой хороший вывод со всеми возможными строками, как в «статусе» для addPet в примере, упомянутом в вопросе. Поскольку я следую той же схеме JSON, что и в этом демонстрационном json — petstore.swagger.wordnik.com/v2/swagger.json — не могли бы вы сказать мне, как я должен изменить определение питомца для статуса, чтобы достичь того же результата, что и в онлайн-демонстрации?

2. Какую версию пользовательского интерфейса использовать? Когда я протестировал его, он работал нормально.

3. Я использую версию версии 2.0.47 и пытаюсь изменить json в этом примере: github.com/swagger-api/swagger-ui/tree/master/dist . Если бы вы могли изменить этот json: petstore.swagger.wordnik.com/v2/swagger.json и брось это где-нибудь в Интернете, я был бы признателен

4. Вы смотрите не на тот файл. Проверить swagger-ui.js вместо этого.

5. Моя плохая версия — 2.1.0-альфа.7, которая, похоже, является последней. Можете ли вы определить перечисление в этом примере github ?

Ответ №2:

Обновите это с помощью синтаксиса YAML.

OpenAPI 2.0:

 parameters:
  - in: query
    name: sample
    description: a sample parameter with an enum value
    type: string
    enum:
      - 1
      - 2
    required: true

OpenAPI 3.0:

 parameters:
  - in: query
    name: sample
    description: a sample parameter with an enum value
    schema:
      type: string
      enum:
        - 1
        - 2
    required: true

Ответ №3:

Это должно сработать:

 {
    "name": "bookingType",
    "in": "path",
    "type": "array",
    "items": {
        "enum": [
            "packages", "accommodations"
        ]
    },
    "description": "lorem ipsum"
}

Ссылка https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#itemsObject

Ответ №4:

Это не точный ответ, но он может сработать для вас, пока они не добавят эту функциональность.

Просто объявите свойство таким образом

 "MyObject":{
   "properties":{
      "MyEnum":{
         "type":"Value1 or Value2 or Value3"
      }
   }
}

Ваша модель будет показана {} , но Модель покажет MyEnum(Value1 or Value2 or Value3, optional)