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

Прочее:

 . [[https://stoplight.io/open-source/prism|An open-source HTTP mock and proxy server]]

== Алиасы ==

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

== Редактирование ==

=== swagger-editor ===

{{{#!highlight bash
docker run --rm -it \
    -p 8080:8080 \
    swaggerapi/swagger-editor
}}}

=== swagger-ui ===

[[https://swagger.io/docs/open-source-tools/swagger-ui/usage/installation/|Установка]]

Запуск сервера UI с отображением API через *url*

{{{#!highlight bash
docker run --rm -it \
    -p 80:8080 \
    -e API_URL=http://generator.swagger.io/api/swagger.json \
    swaggerapi/swagger-ui
}}}

Переходим по [[http://localhost]] и наблюдаем отображение *swagger.json*

Для отображение произвольного json можно воспользоваться параметром *url* :

[[http://localhost/?url=https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml#/default/findPets]]

Запуск сервера UI с отображением API через файл

{{{#!highlight bash
docker run --rm -it \
    -p 80:8080 \
    -v /path/to/my/specs:/opt/specs \
    -e SWAGGER_JSON=/opt/specs/swagger.json \
    swaggerapi/swagger-ui
}}}

Несколько JSON-файлов в UI

Данное решение предполагает замену директории */usr/share/nginx/html* в запускаемом контейнере *swagger-ui*

{{{#!highlight bash
# --- клонируем репозиторий swagger-ui
git clone --depth=1 git@github.com:swagger-api/swagger-ui.git
# --- создаем монтируюмую директорию и копируем туда всё из dist
mkdir myhtml
cp -r swagger-ui/dist/* myhtml
# --- копируем туда же свои swagger.json-ы
cp /path/to/my/swagger/files/* myhtml/
# --- запускаем контейнер swagger-ui
docker run --rm -it \
    -p 80:8080 \
    -v /path/to/myhtml:/usr/share/nginx/html \
    -e SWAGGER_JSON=base-name-of-default-file.json \
    swaggerapi/swagger-ui
}}}

Переходим на [[http://localhost]] и наблюдаем наш файл. Для отображения другого json-файла задаем адрес [[http://localhost?url=another-swagger-file.json]]

=== VSCode ===

Устанавливаем 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]]


== Валидация ==

[[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
}}}

[[https://github.com/apigee-127/swagger-tools|swagger-tools]]

{{{#!highlight bash
sudo npm install -g swagger-tools
swagger-tools validate swagger/app.json
....
92 errors and 0 warnings
echo $?
1
swagger-tools validate ~/tmp/swagger.json
echo $?
0
}}}