Swagger
Swagger, теперь известный как OpenAPI Specification (OAS), - это широко используемый фреймворк для проектирования, документирования и тестирования API. Он предоставляет стандартизированный способ описания функциональности API, что упрощает понимание и взаимодействие с API разработчикам, а также позволяет автоматизированным инструментам генерировать клиентский код, серверные заглушки и интерактивную документацию.
Ключевые особенности Swagger/OpenAPI включают:
- Документация API: Он позволяет разработчикам определить конечные точки API, типы данных запросов и ответов, заголовки, методы аутентификации и многое другое с использованием машиночитаемого формата (обычно JSON или YAML).
- Интерактивная документация: Swagger генерирует интерактивную и понятную человеку документацию для API. Эта документация позволяет разработчикам исследовать и тестировать конечные точки API напрямую из веб-браузера, что упрощает понимание работы API.
- Генерация кода: На основе спецификации API Swagger может генерировать клиентские библиотеки, серверные заглушки и документацию API на различных языках программирования. Это ускоряет разработку и обеспечивает согласованность между спецификацией API и фактическим кодом.
- Валидация: Спецификацию можно использовать для проверки запросов и ответов, что помогает выявлять ошибки на ранних этапах разработки.
- Тестирование: Документация Swagger часто включает интерактивные функции, которые позволяют разработчикам отправлять запросы к конечным точкам API и просматривать ответы. Это помогает тестировать функциональность API.
- Подход "Проектирование сначала": Swagger поощряет подход "проектирование сначала", при котором спецификация API создается перед написанием кода. Это помогает проектировать хорошо структурированные и согласованные API.
- Совместная работа: Стандартизированный формат Swagger/OAS обеспечивает лучшую совместную работу между командами разработчиков, а также с сторонними разработчиками, которые хотят интегрироваться с API.
- Версионирование: Версионирование API может быть обработано в спецификации Swagger, что четко указывает, к какой версии API относится каждая конечная точка.
Спецификация OpenAPI широко поддерживается в различных языках программирования и фреймворках. Она стала неофициальным стандартом для документации и проектирования API благодаря четкой структуре, широкой поддержке инструментов и фокусу как на человекочитаемой документации, так и на машинопонимаемых контрактах API.
Полезные ссылки
- https://swagger.io/
- https://www.openapis.org/
- OpenApi Specification v3.1.0 | Data Types
- Using $ref
- File Upload
- Describing Responses
- Examples
- Representing XML
Аналоги swagger:
- dapperdox
- What API documentation generator/tool do you use?
- https://redoc.ly/
- https://stoplight.io/studio/
Алиасы
alias swal='swagger-cli validate swagger.yml' alias swaal='swagger-cli validate swagger.yaml' alias swau='docker run --rm -it -p 80:8080 -v $(pwd):/swagger -e SWAGGER_JSON=/swagger/swagger.yml swaggerapi/swagger-ui' alias swaau='docker run --rm -it -p 80:8080 -v $(pwd):/swagger -e SWAGGER_JSON=/swagger/swagger.yaml swaggerapi/swagger-ui'
Валидация
sudo npm install -g @apidevtools/swagger-cli swagger-cli validate path/to/swagger.yml
npx @redocly/openapi-cli lint path/to/swagger.yml --format stylish --skip-rule info-license