Блог

Главная - Вопросы по программированию - Пример данных составной формы OpenAPI

Пример данных составной формы OpenAPI

#schema #multipartform-data #openapi

Вопрос:

У меня есть сообщение с данными из нескольких частей/форм в конечной точке API, которое принимает некоторые строки ключа/значения и загружает файл с помощью ключа files .

Я считаю, что правильно определил его в OpenAPI;

 "requestBody": {
  "required": true,
  "content": {
    "multipart/form-data": {
      "schema": {
        "properties": {
          "file": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "binary"
            }
          },
          "myKey1": {
            "type": "string"
          },
          "myKey2": {
            "type": "string"
          }
        }
      },
      "examples": {
        "value": ?
      }
    }
  }
},

Однако я не уверен, как я могу описать пример для составных/форм-данных в examples поле.

Я предполагаю, что мне не нужно представлять файл (хотя это было бы бонусом), а только myKey1 ключи myKey2 и значения.

Ответ №1:

Ваше определение OAS кажется правильным. Вы можете определить примеры, как показано ниже:

       "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "example": [
                      {
                        "externalValue": "http://www.africau.edu/images/default/sample.pdf"
                      }
                    ]
                  },
                  "myKey1": {
                    "type": "string",
                    "example": "myKey1Example"
                  },
                  "myKey2": {
                    "type": "string",
                    "example": "myKey2Example"
                  }
                }
              }
            }
          }
        },

externalValue можно добавить, чтобы указать URL-адрес файла образца в спецификации Open API. Это только для целей документа.

Однако он не будет отображаться в пользовательском интерфейсе swagger, так как swagger-ui его еще не поддерживает. Это отслеживается в [1].

[1] https://github.com/swagger-api/swagger-ui/issues/5433

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

1. Хорошо, спасибо, я понимаю вариант использования example , но можете ли вы предоставить вариант использования для examples массива?

2. Он используется только для обозначения того, что пользователь API может загружать на этот ресурс более одного файла

3. Ты уверен? Судя по тому, как читается спецификация, похоже examples , что это множество различных примеров

4. externalValue поддерживается только в типе носителя examples (множественное exampleS число ), он не поддерживается в схеме/свойстве example .

5. @myol, Извините, у меня сложилось впечатление, что вы спрашиваете о массиве примеров в этих вопросах. Да, examples используется для предоставления нескольких примеров для параметра. Вы можете получить более подробную информацию здесь .

Метки: