API с помощью Swagger

Цель: научиться описывать API с помощью спецификации OpenAPI, описывать конечные точки, параметры, ответы с помощью. Генерировать описание с помощью Swagger.

Содержание и порядок выполнения лабораторной работы

1. Изучить основы OpenAPI, Swagger, разобраться в важности документирования API. Изучить основные составляющие Swagger: спецификация OpenAPI, Swagger Editor, Swagger UI и Swagger Codegen.
2. Используя наработки из предыдущей лабораторной работы, определить входные параметры, ожидаемые выходные данные и сообщения об ошибках для каждой конечной точки.
3. Создать YAML-файл для документации API или JSDoc комментарии для путей, описывающих из фактическую логику работы. Можно использовать Swagger Editor для написания спецификации OpenAPI для API. Спецификация должна включать описание API, каждой конечной точки, ее параметров, ответов и любых требований безопасности, если они есть.
4. Протестировать каждую конечную точку API, используя пользовательский интерфейс Swagger, и убедиться, что API работает как ожидается.
5. Зафиксировать результаты работы с помощью системы контроля версий git и отправить репозиторий на github.

Требования

• API функционирует и возвращает ожидаемые ответы.
• Документация Swagger ясна и лаконична и включает всю необходимую информацию и соответствует логике работы сервера.
• Для просмотра и взаимодействия с документацией API используется пользовательский интерфейс Swagger.
• Конечные точки API тестируются с помощью пользовательского интерфейса Swagger.

Результаты выполнения лабораторной работы

1. Работающий локально сервер с подключением к бд и логикой, которая соответствует требованиям. Код сохранен в системе контроля версий.
2. Отдельный документ, содержащий спецификацию OpenAPI для API в YAML или рядом с вашим кодом с помощью JSDoc.
3. Пользовательский интерфейс сгенерированные с помощью Swagger UI, показывающий конечные точки API и их ответы.

Источники

1. Swagger (OpenAPI 3.0)
2. Знакомство со спецификациями OpenAPI и Swagger
3. Руководство по документации Swagger
4. Документация по пользовательскому интерфейсу Swagger
5. Documenting your Express API with Swagger
6. How to Document an Express API with Swagger UI and JSDoc
7. Пример с JSDoc

Вопросы

1. Что такое OpenAPI?
2. Назовите основные объекты в спецификации OpenAPI.
3. Примеры полей и их значений, используемых для описания API.
4. Что такое YAML?
5. Чем YAML отличается от JSON?
6. Для чего используется JSDoc?
7. Для чего используются Swagger Editor, Swagger UI и Swagger Codegen.