Недавно мы рассмотрели тему ускорение разработки вашего спокойного API с помощью Swagger. В статье действительно ясно показано, как использовать swagger, и я бы посоветовал вам сначала прочитать ее, прежде чем проходить через это.

Однако статья начинается с API с нуля. Но это может быть не так для некоторых из нас. У меня, например, был API, который уже существовал. Если вам интересно, как использовать Swagger для вашего уже созданного и размещенного API, приготовьтесь к короткому, но интересному краткому совету.

Интерфейс Swagger

Swagger UI — это прекрасный вид, который мы видим, когда документируем наш API с помощью swagger. В readme проекта это определяется так:

Пользовательский интерфейс Swagger – это независимая коллекция ресурсов HTML, Javascript и CSS, которая динамически создает красивую документацию из совместимого с Swagger API. http://swagger.io

Мы можем использовать Swagger UI одним из двух способов:

  1. КАК ЕСТЬ: это включает в себя просто копирование содержимого папки dist и редактирование источника файла конфигурации. (либо .yaml, либо .json)
  2. Сборка . Это включает в себя клонирование репозитория пользовательского интерфейса 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.