OpenAPI спецификация

OpenAPI спецификация (OAS, от OpenAPI Specification) определяет формализованный стандарт, который описывает интерфейс к REST API сервису.

Полное описание формата разработки спецификации OAS можно найти на официальном сайте OpenAPI Specification (https://spec.openapis.org/oas/v3.0.1). В текущей статье будут описаны основные особенности и рекомендации по написанию собственной спецификации OpenAPI для разрабатываемой системы. В качестве примера будет рассмотрена спецификация для REST-сервиса, который предоставляет информацию о животных.

Примечание: На данный момент не поддерживается использование перечислений (enum) в описании OpenAPI спецификации. При создании API, учтите, что значения enum не будут обработаны.

Формат спецификации

Файл спецификации может быть представлен в форматах JSON или YAML. Вы можете воспользоваться веб-интерфейсом Swagger (https://editor.swagger.io/) для написания и редактирования OAS в формате YAML, с последующей возможностью экспорта спецификации в JSON формат.

top

Версия и информация о сервисе:

  • Обязательно. Версия конкретной спецификации определяется полем openapi в начале каждого документа OAS.

  • Обязательно. Блок info служит для размещения основной информации о вашем сервисе, включая:

    • title: Название сервиса (обязательное поле).

    • version: Версия сервиса (обязательное поле).

Определение серверов:

  • Опционально. Используйте блок servers для указания серверов, на которых будет доступен ваш сервис. Укажите URL сервера и добавьте описание, если необходимо.

path 1
path 2

Определение путей:

  • Обязательно. Создайте блок paths для определения доступных путей (эндпоинтов) в вашем сервисе. Каждый путь начинается с URL-префикса и содержит методы (GET, POST и т. д.) для обработки запросов.

  • Опционально. При необходимости добавьте теги (tags), чтобы организовать методы в группы.

  • Опционально. Заполните operationId для каждого метода.

  • Определите следующие поля для методов, которые требуют передачи параметров или данных в запросе:

    • Параметры запроса определяются в блоке parameters.

    • Тело запроса: для метода POST и других методов, которые требуют передачи данных, укажите параметр requestBody.

  • Обязательно. Создайте блок responses для описания возможных ответов. Обязательно укажите description и определите content и тип формата.

components

Определение компонентов и схем данных:

  • Создайте блок components, где определите схемы данных и ссылки на них.

  • Также, вместо определения схем данных в блоке components, вы можете описать сами схемы непосредственно внутри определения путей в блоке schemas.

Скачать пример описания REST API.