Недавно мы рассмотрели тему ускорение разработки вашего спокойного API с помощью Swagger. В статье действительно ясно показано, как использовать swagger, и я бы посоветовал вам сначала прочитать ее, прежде чем проходить через это.
Однако статья начинается с API с нуля. Но это может быть не так для некоторых из нас. У меня, например, был API, который уже существовал. Если вам интересно, как использовать Swagger для вашего уже созданного и размещенного API, приготовьтесь к короткому, но интересному краткому совету.
Интерфейс Swagger
Swagger UI — это прекрасный вид, который мы видим, когда документируем наш API с помощью swagger. В readme проекта это определяется так:
Пользовательский интерфейс Swagger – это независимая коллекция ресурсов HTML, Javascript и CSS, которая динамически создает красивую документацию из совместимого с Swagger API. http://swagger.io
Мы можем использовать Swagger UI одним из двух способов:
- КАК ЕСТЬ: это включает в себя просто копирование содержимого папки dist и редактирование источника файла конфигурации. (либо .yaml, либо .json)
- Сборка . Это включает в себя клонирование репозитория пользовательского интерфейса Swagger, внесение нескольких изменений в соответствии с вашими предпочтениями и создание собственной сборки. Будет сгенерирована папка dist, которую вы затем сможете использовать для редактирования конфигурационного файла.
Мы воспользуемся последним подходом для документирования небольшого API. Поскольку это статья с кратким советом, мы задокументируем три маршрута для Open Github API, пытаясь максимально его настроить.
Настраивать
Клонируйте репозиторий пользовательского интерфейса Swagger и установите зависимости.
# Clone the repo $ git clone https://github.com/swagger-api/swagger-ui.git # cd into the folder $ cd swagger-ui # Install dependecies $ npm install # install gulp globally $ npm install -g gulp # Build Swagger $ gulp build
Хотя каталог dist уже существует, build удаляет все и заново создает каталог dist каждый раз, когда вы его запускаете.
Откройте файл dist/index.html в браузере или, что еще лучше, откройте папку dist с помощью httpster.
# install httpster $ npm install -g httpster # serve the dist folder $ httpster -d dist
Откройте http://localhost:3333, чтобы увидеть отображение пользовательского интерфейса swagger по умолчанию.
Настройка Swagger
Первоначально опубликовано на www.laravelfeed.com.