Syntax highlighting of doc/swagger
= Swagger = <<TableOfContents()>> 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://www.openapis.org/]] . [[https://swagger.io/]] . [[https://hub.docker.com/u/swaggerapi|Образы swagger]] . [[https://swagger.io/specification/|OpenApi Specification v3.1.0]] | [[https://swagger.io/docs/specification/data-models/data-types/|Data Types]] . [[https://swagger.io/docs/specification/using-ref/|Using $ref]] . [[https://swagger.io/docs/specification/describing-request-body/file-upload/|File Upload]] . [[https://swagger.io/docs/specification/describing-responses/|Describing Responses]] . [[https://github.com/OAI/OpenAPI-Specification/tree/main/examples|Examples]] . [[https://swagger.io/docs/specification/data-models/representing-xml/|Representing XML]] . [[https://davidgarcia.dev/posts/how-to-split-open-api-spec-into-multiple-files/|How to split a large OpenAPI document into multiple files]] . [[https://developer.mozilla.org/ru/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types|Неполный список типов MIME]] Аналоги swagger: . [[http://dapperdox.io/|dapperdox]] . [[https://dev.to/artis3n/what-api-documentation-generator-tool-do-you-use-2bi|What API documentation generator/tool do you use?]] . [[https://redoc.ly/]] . [[https://stoplight.io/studio/]] == Алиасы == {{{#!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' }}} == Валидация yaml== [[https://github.com/APIDevTools/swagger-cli|swagger-cli]] {{{#!highlight bash sudo npm install -g @apidevtools/swagger-cli swagger-cli validate path/to/swagger.yml }}} [[https://github.com/Redocly/openapi-cli|openapi-cli]] {{{#!highlight bash npx @redocly/openapi-cli lint path/to/swagger.yml --format stylish --skip-rule info-license }}} == VSCode как редактор OpenAPI == Устанавливаем vscode {{{#!highlight bash sudo snap install --classic code }}} Устанавливаем расширения: . [[https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi|OpenAPI (Swagger) Editor]] . [[https://marketplace.visualstudio.com/items?itemName=zoellner.openapi-preview|OpenAPI Viewer]] . [[https://marketplace.visualstudio.com/items?itemName=vscodevim.vim|Vim Mode]] . [[https://marketplace.visualstudio.com/items?itemName=Atif.vs-redoc-viewer|ReDoc Viewer]]