Syntax highlighting of doc/swagger

= 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/]]

== Алиасы ==

{{{#!highlight bash
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'
}}}