Документирование вашего API с помощью стандарта OpenAPI


Что такое OpenAPI?

Стандарт OpenAPI является наиболее широко принятым отраслевым стандартом для описания новых и старых API. С его помощью вы можете описать маршруты, HTTP-методы, заголовки, тела, ответы, информацию для доступа и многое другое. Стоит сказать, что стандарт OpenAPI не может описать любой вид API, он имеет свои ограничения.

Достижения OpenAPI

Согласно документу «Начало работы OpenAPI Initiative», использование стандарта для описания API дает возможность выполнять следующие действия:

  • Валидация и линтинг описания: Проверьте, что ваш файл описания синтаксически корректен и придерживается конкретной версии Спецификации и остальных рекомендаций вашей команды по форматированию.
  • Валидация данных: Проверьте правильность данных, проходящих через ваш API (в обоих направлениях), во время разработки и после развертывания.
  • Генерация документации: Создание традиционной человекочитаемой документации на основе машиночитаемого описания, которое всегда остается актуальным.
  • Генерация кода: Создание серверного и клиентского кода на любом языке программирования, освобождая разработчиков от необходимости выполнять проверку данных или, например, писать код клея для SDK.
  • Графические редакторы: Позволяют легко создавать файлы описаний с помощью графического интерфейса, вместо того чтобы набирать их вручную.
  • Макетные серверы: Создавайте фальшивые серверы, предоставляющие примеры ответов, которые вы и ваши клиенты можете начать тестировать до того, как напишете хоть одну строчку кода.
  • Анализ безопасности: Обнаружение возможных уязвимостей на этапе разработки API, а не намного позже.

Лучшие практики OpenAPI

Существует ряд рекомендаций, данных инициативой OpenAPI для создания лучших документов спецификации. Среди них: использовать подход «проектирование — сначала», хранить единый источник правды, ****Добавить документы OpenAPI в систему контроля исходных текстов, сделать документы OpenAPI доступными для пользователей, редко писать документы OpenAPI вручную и работать с большими документами. Ознакомьтесь с каждым из них по ссылке.

Инструменты OpenAPI

Существует бесчисленное множество отличных инструментов для работы с этим стандартом, с которыми вы можете ознакомиться здесь, но я покажу вам только те, которые лучше всего подходят для моего рабочего процесса. Вот эти инструменты:

Redocly CLI

Этот инструмент помогает вам линтировать файлы, объединять, связывать и разделять их. Я выбрал его, потому что он позволил мне не повторяться, разбивая спецификацию на множество файлов с параметрами, ответами, моделями и так далее. Вы также можете объединить две разные версии спецификации, чтобы, например, выпустить частную и публичную версии API, и предварительно просмотреть свою спецификацию через браузер.

В Redocly есть отличное расширение, которое предоставляет языковой сервер, помогающий работать с файлами типа OpenAPI. Если вы используете vim/neovim с coc.nvim, я создал простое расширение для работы с ним расширения Redocly.

Посмотрите инструмент здесь: https://redocly.com/docs/cli/

Prism CLI

Prism CLI предоставляет вам возможность создать имитатор сервера, прокси-сервер для реального API, следуя определению и шаблонам, заданным в файле спецификации, и линтингу, как Redocly CLI. Процесс имитации важен, например, когда у вас нет реализованного реального API и вам нужно его протестировать. Прокси-процесс помогает вам гарантировать, что реальный API реализован так, как указано.

У Prism также есть клиент, который можно использовать для имитации и проксирования API, что позволяет создавать интеграционные и контрактные тесты, все из файла спецификации OpenAPI. Лично я еще не делал этого, но это следующий шаг для реализации. Думаю, я также задокументирую свой опыт.

Ознакомьтесь с инструментом здесь: https://meta.stoplight.io/docs/prism/ZG9jOjk0-prism-cli

Генератор OpenAPI

Вы узнали о стандарте, прочитали о лучших практиках, использовали инструменты для создания документации API, и теперь вы можете создать сервер или клиента; именно для этого и существует OpenAPI Generator. Этот инструмент получает в качестве входных данных пакетный файл OpenAPI и генерирует клиент или сервер для определенного вами языка/фреймворка.

Он предоставит вам полностью функциональный, в зависимости от выбранного вами генератора, клиентский слой для отправки запросов к серверу API или серверный слой для получения этих запросов. Инструмент не совершенен, некоторые генераторы не имеют некоторых функций, что делает важным тщательный выбор генератора.

Postman и Insomnia

Когда ваша спецификация готова, вы можете использовать ее с другими инструментами для тестирования вашего API. В дополнение к тому, что я говорил о Prism client, mock и proxy из файла OpenAPI, вы можете загрузить этот файл спецификации в такой инструмент, как Postman или Insomnia, чтобы иметь возможность тестировать любые запросы вручную, когда это необходимо.

Ознакомьтесь с этим инструментом здесь: https://github.com/OpenAPITools/openapi-generator

Swagger

Невозможно говорить об OpenAPI, не упомянув Swagger и его инструменты. Как говорится на его сайте: swagger — это набор инструментов с открытым исходным кодом, построенных вокруг спецификации OpenAPI, которые помогут вам проектировать, создавать, документировать и использовать REST API.

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

Заключение

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

Это мой опыт использования стандарта OpenAPI; я все еще нахожусь в начале пути, и мне еще многое предстоит узнать и сделать. Однако я думаю, что этот опыт может помочь кому-то ускорить процесс создания спецификации OpenAPI и понять, насколько она мощная.

Спасибо, что прочитали. Если у вас есть какие-либо отзывы; я буду очень признателен, поскольку одна из целей этого поста — задокументировать то, чему я научился, и помочь кому-то еще в этом процессе.

Оцените статью
Procodings.ru
Добавить комментарий