Создавайте первоклассную документацию для ваших API с помощью OpenAPI

Если вы разработчик, вы, вероятно, не раз работали с REST API. Если да, то вы, вероятно, знаете, как больно работать с плохо документированным (или, что еще хуже, недокументированным) API. По этой причине, когда мы разрабатываем API, очень важно хорошо его задокументировать. Таким образом, вы упростите жизнь разработчикам, которые захотят с ним работать, и вашему будущему.

Одним из самых популярных стандартов для документирования REST API является OpenAPI, часто называемый Swagger, несмотря на то, что это также название инструментов, которые вы используете для создания и просмотра этих документов. Документ OpenAPI написан на JSON или YAML и описывает, как использовать конечные точки, которые предоставляет ваш API, а также другие детали, такие как механизмы аутентификации. Из этого документа можно сгенерировать удобную для пользователя HTML-документацию, а также клиентские и серверные заглушки на различных языках программирования и средах.

Лучше всего то, что все это можно сделать бесплатно. Сегодня я собираюсь показать вам, как задокументировать фиктивный API для библиотеки книг, используя OpenAPI в его версии YAML. Наш API библиотеки будет предлагать только базовые операции CRUD:

  • GET /books: получить все доступные книги
  • GET /books/{id}: получить сведения о книге с определенным идентификатором
  • GET /books/search: получить все книги, соответствующие критериям поиска (название, автор…)
  • POST /books: создать новую книгу
  • PUT /books/{id}: обновить сведения о книге с определенным идентификатором
  • DELETE /books/{id}: удалить книгу с определенным идентификатором

Для создания, изменения и удаления книги потребуется ключ API. Наш объект book также будет очень простым, со следующими свойствами:

  • ID: уникальный идентификатор
  • Title
  • Author
  • Year (необязательно)
  • Pages (необязательно)
  • TypeOfBook (необязательно): может быть одним из следующих: роман, энциклопедия, комикс, биография и история.

Вы готовы написать свой первый документ OpenAPI? Пойдем!

Основная информация об API

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

Для большинства REST API требуется какой-либо тип аутентификации. В нашем случае мы выберем простой ключ API, который будет отправлен в виде строки запроса для тех операций, которые требуют аутентификации (создание, изменение и удаление книги):

Определение модели данных (схемы)

Теперь давайте определим Book модель данных, о которой мы говорили ранее. Как мы уже говорили, у книги должны быть идентификатор, название и автор. При желании он может иметь год публикации, количество страниц и тип книги (роман, энциклопедия, комикс, биография или история). Внутри тега components на том же уровне, что и securitySchemes, мы можем определить нашу схему Book:

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

Определение конечных точек

ПОЛУЧИТЬ / книги

Начнем с самого простого. Единственный возможный ответ - это HTTP 200 с массивом JSON, содержащим все книги, доступные в библиотеке, как объекты с ранее определенной схемой Book.

ПОЛУЧИТЬ / книги / {id}

Что, если мы просто хотим получить подробную информацию о конкретной книге? Задайте в пути параметр id, затем добавьте ошибку ответа 404 на случай, если книги с запрошенным идентификатором нет:

ПОЛУЧИТЬ / книги / поиск

Для конечной точки поиска параметры будут необязательными и будут отправлены в виде строк запроса. Также обратите внимание, что мы не определяем ответ 404 - поэтому, если нет книг, соответствующих критериям поиска, наш API просто вернет пустой массив JSON:

ПОЧТА / книги

При вызове этого метода клиент отправляет сведения о новой книге в виде объекта JSON в теле запроса POST, используя ранее определенную схему Book. Поскольку это write операция, пользователю необходимо будет пройти аутентификацию с помощью действующего ключа API для выполнения этого вызова (тег security). Наконец, вспомните, как теперь определяются три возможных кода ответа.

PUT / books / {id}

Как и в случае с конечной точкой GET /books/{id}, здесь мы получаем идентификатор книги, которую нужно изменить, из параметра пути и новые данные из тела запроса, как в POST /books:

УДАЛИТЬ / книги / {id}

То же, что и в предыдущем примере, но без тела запроса:

В этой статье я рассмотрел основные аспекты спецификации OpenAPI на нескольких очень простых примерах. Конечно, OpenAPI предлагает гораздо больше возможностей - я рекомендую вам прочитать официальную документацию и продолжать изучать ее после того, как вы закончите читать это. Также хочу порекомендовать вам несколько интересных инструментов для работы с OpenAPI:

  • Расширение OpenAPI (Swagger) Editor для Visual Studio Code: оно проверяет ваш код OpenAPI, вносит предложения, позволяет вам предварительно просмотреть, как он будет выглядеть в пользовательском интерфейсе Swagger…
  • Swagger UI: доступный бесплатно в облаке, а также для загрузки на ваш компьютер, Swagger UI преобразует ваш код JSON или YAML в очень удобную HTML-документацию, из которой вы даже можете опробовать API.
  • Swagger Codegen: этот инструмент может преобразовать ваш документ OpenAPI в заглушку (каркас) для сервера и для клиента на различных языках программирования и фреймворках.

Я также хочу поделиться с вами полным документом OpenAPI, который мы создали в этой публикации, и показать, как он будет выглядеть в пользовательском интерфейсе Swagger: