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://www.openapis.org/
• https://swagger.io/
• Образы swagger
• OpenApi Specification v3.1.0 | Data Types
• Using $ref
• File Upload
• Describing Responses
• Examples
• Representing XML

• How to split a large OpenAPI document into multiple files

• Неполный список типов MIME

Аналоги swagger:

• dapperdox
• What API documentation generator/tool do you use?
• https://redoc.ly/
• https://stoplight.io/studio/

Прочее:

• An open-source HTTP mock and proxy server

Алиасы

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

docker run --rm -it \
    -p 8080:8080 \
    swaggerapi/swagger-editor

swagger-ui

Установка

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

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 через файл

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*

# --- клонируем репозиторий 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

sudo snap install --classic code

Устанавливаем расширения:

• OpenAPI (Swagger) Editor
• OpenAPI Viewer
• Vim Mode
• ReDoc Viewer

Валидация

swagger-cli

sudo npm install -g @apidevtools/swagger-cli
swagger-cli validate path/to/swagger.yml

openapi-cli

npx @redocly/openapi-cli lint path/to/swagger.yml --format stylish --skip-rule info-license

swagger-tools

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