Cómo Configurar Swagger UI para un Proyecto de Rails

Crear documentación API clara e interactiva es una parte crítica del desarrollo de un servicio web mantenible y accesible. Swagger UI sirve como una interfaz de documentación dinámica para desarrolladores, y su integración en tu proyecto de Ruby on Rails puede mejorar enormemente la experiencia del desarrollador. En este post, desglosamos el proceso de configuración de Swagger UI utilizando dos gemas populares, grape-swagger para APIs Grape, y rswag para documentación API con RSpec.

Parte 1: Para APIs Grape

Grape es un micro-framework API similar a REST para Ruby, diseñado para ejecutarse en Rack o complementar un marco de aplicación web existente como Rails. Grape-swagger proporciona documentación autogenerada para tu API Grape.

Paso 1: Instalación de `grape-swagger`

Agrega grape-swagger a tu Gemfile y ejecuta bundle install para añadirlo a tu proyecto:

gem 'grape-swagger'

Y luego ejecuta:

bundle install

Paso 2: Configuración de `grape-swagger`

Configura un inicializador para 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

Paso 3: Definición de Entidades y Documentación de la API

Necesitas definir tus entidades API para que grape-swagger pueda documentarlas:

# 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

Paso 4: Añadir Endpoints de Swagger

En tu clase base de API, añade la ruta de documentación de swagger para que pueda servir el JSON de Swagger:

# app/api/base.rb

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

Paso 5: Visualización de tu Documentación Swagger

Ahora puedes acceder a tu Swagger UI navegando a http://localhost:3000/swagger.

Parte 2: Para una aplicación Rails usando RSpec

rswag se integra con RSpec para generar automáticamente documentación de API compatible con Swagger basada en tus pruebas de API.

Paso 1: Instalación de `rswag-specs`

Añade rswag-specs a tu Gemfile e instálalo:

gem 'rswag-specs'

Y luego ejecuta:

bundle install

Paso 2: Generación de Configuración y Archivos

Ejecuta el generador de RSwag para crear la configuración inicial y los directorios para tus especificaciones de API:

rails g rswag:install

Paso 3: Escribir Especificaciones de Solicitud con Swagger DSL

Crea un archivo de especificación y utiliza el DSL de RSwag para probar tus endpoints y documentarlos:

# 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

Paso 4: Acceder a Tu Documentación de API con RSwag UI

RSwag proporciona una interfaz Swagger UI a la que puedes acceder en http://localhost:3000/api-docs. Esta interfaz refleja directamente las especificaciones que has escrito.

Alternativa

Si no deseas escribir RSpec, o no estás usando GrapeAPI, puedes probar nuestra última herramienta de automatización: Cordyline.

Generar Documentación Swagger Automáticamente

Con solo un arrastrar y soltar, generaremos toda la documentación Swagger para ti sin una sola línea de código.