Revert to this revision

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/

Алиасы

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'