Swagger Docs Rails

Gem Rails Engine para gerar documentação OpenAPI 3.0 a partir do db/schema.rb, controllers Rails e rotas da aplicação.

Instalação

Adicione ao Gemfile da API:

gem "swagger_docs_rails"

Para desenvolvimento local:

gem "swagger_docs_rails", path: "../swagger_docs_rails"

Execute:

bundle install
rails generate swagger_docs_rails:install

Adicione as rotas:

if ENV["ENABLE_SWAGGER"] == "true"
  mount SwaggerDocsRails::Engine => "/"
end

Configuração

O generator cria config/initializers/swagger_docs_rails.rb:

SwaggerDocsRails.configure do |config|
  config.enabled = !Rails.env.production?
  config.title = Rails.application.class.module_parent_name
  config.version = "1.0.0"
  config.description = "Documentação OpenAPI gerada automaticamente"
  config.server_url = ENV.fetch("HOST_URL", "/")
  config.live_reload = Rails.env.development?
  config.username = ENV.fetch("SWAGGER_USER", "admin")
  config.password = ENV.fetch("SWAGGER_PASSWORD", "")
  config.additional_controller_paths = []
  config.output_path = Rails.root.join("public", "swagger", "openapi.json")

  # Autenticação no Swagger UI (botão Authorize)
  config.security_schemes = [
    { name: "BearerAuth", type: :http, scheme: "bearer", bearer_format: "JWT",
      description: "Token JWT" },
    { name: "ApiKeyAuth", type: :api_key, in: "header", param_name: "X-Api-Key",
      description: "Chave interna da API" }
  ]
  config.global_security = [{ BearerAuth: [] }, { ApiKeyAuth: [] }]
end

Autenticação (Bearer, API Key)

A gem gera components.securitySchemes e security global a partir da configuração. No Swagger UI, use Authorize para informar JWT ou API Key; persistAuthorization mantém os valores na sessão.

Tipos suportados em security_schemes:

type	Campos principais
:http	scheme, bearer_format, description
:api_key	param_name (ou header_name), in (header/query)

global_security define quais esquemas exigir. Vários hashes em sequência = OR (Bearer ou ApiKey):

config.global_security = [{ BearerAuth: [] }, { ApiKeyAuth: [] }]

Uso

Gere o arquivo OpenAPI:

rails swagger:generate

Valide o arquivo gerado, se a aplicação possuir openapi_parser:

rails swagger:validate

Com ENABLE_SWAGGER=true, acesse:

• /swagger
• /swagger/doc
• /swagger/cache com método DELETE