Как настроить Swagger UI для проекта на Rails

Создание четкой, интерактивной документации API является важной частью разработки поддерживаемого и доступного веб-сервиса. Swagger UI служит динамическим интерфейсом документации для разработчиков, и его интеграция в ваш проект на Ruby on Rails может значительно улучшить опыт разработчика. В этом посте мы разбираем процесс настройки Swagger UI с использованием двух популярных гемов: grape-swagger для Grape API и rswag для документации API с помощью RSpec.

Часть 1: Для Grape API

Grape — это микро-фреймворк для API, похожий на REST, для Ruby, который предназначен для работы на Rack или дополнения существующего фреймворка веб-приложений, такого как Rails. Grape-swagger предоставляет автоматически сгенерированную документацию для вашего Grape API.

Шаг 1: Установка `grape-swagger`

Добавьте grape-swagger в ваш Gemfile и выполните bundle install, чтобы добавить его в ваш проект:

gem 'grape-swagger'

Затем выполните:

bundle install

Шаг 2: Настройка `grape-swagger`

Настройте инициализатор для grape-swagger:

# config/initializers/swagger.rb

if defined?(Grape)
  GrapeSwaggerRails.options.url      = "/api/swagger_doc"
  GrapeSwaggerRails.options.app_name = "MyApp"
  GrapeSwaggerRails.options.app_url  = "/"
end

Шаг 3: Определение сущностей API и документации

Вам нужно определить сущности вашего API, чтобы grape-swagger мог их документировать:

# app/api/entities/my_entity.rb

module API
  module Entities
    class MyEntity < Grape::Entity
      expose :id, documentation: { type: 'Integer', desc: 'ID of the entity' }
      # ... further code ...
    end
  end
end

Шаг 4: Добавление конечных точек Swagger

В вашем базовом классе API добавьте маршрут документации swagger, чтобы он мог обслуживать Swagger JSON:

# app/api/base.rb

class API::Base < Grape::API
  add_swagger_documentation
end

Шаг 5: Просмотр вашей документации Swagger

Теперь вы можете получить доступ к вашему Swagger UI, перейдя по адресу http://localhost:3000/swagger.


## Часть 2: Для Rails приложения с использованием RSpec

`rswag` интегрируется с RSpec для автоматической генерации API документации, совместимой со Swagger, на основе ваших API тестов.

### Шаг 1: Установка `rswag-specs`

Добавьте `rswag-specs` в ваш `Gemfile` и установите его:

```ruby
gem 'rswag-specs'

А затем выполните:

bundle install

Шаг 2: Генерация конфигурации и файлов

Запустите генератор RSwag для создания начальной конфигурации и директорий для ваших API спецификаций:

rails g rswag:install

Шаг 3: Написание спецификаций запросов с использованием Swagger DSL

Создайте файл спецификации и используйте DSL RSwag для тестирования ваших конечных точек и их документирования:

# spec/integration/my_api_spec.rb

require 'swagger_helper'

describe 'My API' do
  path '/my_api/endpoint' do
    ...
    get 'Retrieves something' do
      produces 'application/json'
      response '200', 'successful' do
        schema type: :object,
               properties: {
                 id: { type: :integer }
               },
               required: ['id']

        # Your test code goes here
      end
    end
  end
end

Шаг 4: Доступ к вашей API документации с помощью RSwag UI

RSwag предоставляет Swagger UI, к которому вы можете получить доступ по адресу http://localhost:3000/api-docs. Этот интерфейс напрямую отражает написанные вами спецификации.

Альтернатива

Если вы не хотите писать на RSpec или не используете GrapeAPI, вы можете попробовать наш последний инструмент автоматизации: Cordyline.

Автоматическая генерация Swagger документации

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