Инструменты документации Swagger для приложения Rails API

Question

Я немного погуглил, чтобы найти правильный и простой способ создания документации Swagger для существующего приложения Rails API.Короче говоря, есть 2 способа реализации: либо через контроллеры, модели или через спецификации контроллера / запроса Rspec.Список не слишком длинный, и сделать выбор не так просто:

1. swagger-docs gem, - самый старый.Плюсы: реализация должна быть сделана в контроллерах.Минусы: не поддерживает Swagger V2 версия и ограничивается только 1.2 .
2. swagger-blocks gem, - улучшенная версия swagger-docs, поддерживает версию Swagger V2, реализация должна осуществляться в контроллерах, моделях.Но я не смог заставить его работать, Редактор Swagger не смог разобрать сгенерированный файл json.
3. rswag gem: расширяет rspec-rails "спецификации запросов" с помощьюSwagger на основе DSL.Лично я обнаружил, что действительно трудно реализовать в существующем приложении Rails по двум причинам:
   • вам придется изменить существующие спецификации запроса
   • спецификации запроса выглядят действительно странно, а синтаксис не RSpec -ish.
4. rspec-rails-swagger gem: реализация через спецификации запроса.Минусы те же, что и выше.

Кто-нибудь знает другие гемы для создания документации Swagger для существующего приложения Rails API?Любые предложения приветствуются!Спасибо.

Answer 1

Я пришел к решению, как использовать rswag gem и rspec-rails-swagger gem - установить rswag gem, добавив в свой Gemfile следующее:

#Gemfile
gem 'rswag-api'
gem 'rswag-ui'

group :development, :test do
  gem 'rspec-rails',         '~> 3.8.1'
  gem 'rspec-rails-swagger', '~> 0.1.5'
...
end

• запустите `bundle install``
• запустите rails g rswag:install, чтобы сгенерировать swagger_helper.rb
• , чтобы создать новую спецификацию запроса с помощью rspec-rails-swagger, запустите rails generate rspec:swagger PostsController (адаптируйте имя к своему выигранному контроллеру, для которого вы хотите написать спецификацию).
• напишите некоторые спецификации, как описано в rspec-rails-swagger README
• run bundle exec rake swagger для создания swagger.json файла.
• монтирование RSwag API и движков пользовательского интерфейса RSwag путем добавления следующих строк в ваш файл routes.rb:

#../config/routes.rb

Rails.application.routes.draw do
  mount Rswag::Ui::Engine => '/api-docs'
  mount Rswag::Api::Engine => '/api-docs'
...#other routes come here
end

• startна вашем сервере rails с помощью rails s
• перейдите к localhost:3000/api-docs, чтобы увидеть сгенерированную документацию Swagger.

Примечание : он работает довольно хорошо и отвечает натребования клиента, а именно:

• генерировать Swagger 2.0 совместимую документацию
• иметь возможность выполнять запросы напрямую изm Интерфейс Swagger для просмотра реальных данных

Я удалил rswag-specs gem из Gemfile, потому что не удалось проверить схему ответа, возвращенную в формате JSON API active_model_serializer гем, который я использую в своем приложении Rails API.Мне всегда приходилось:

• генерировать документы
• комментировать неудачные тесты
• затем раскомментировать неудачные тесты на случай, если мне нужно будет сгенерировать новую документацию, которая была действительнотрудно поддерживать.

Теперь спецификации запросов проверяются RSpec и rspec-rails-swagger одновременно без хлопот.

Надеюсь, это поможет.