OpenAPI & Swagger

Zodra generates OpenAPI 3.1 specifications from your contracts and serves interactive Swagger UI — no extra configuration needed.

Swagger UI

Mount the built-in Swagger UI in your routes:

Rails.application.routes.draw do
  mount Zodra::Swagger => '/docs'
  zodra_routes
end

Visit /docs to browse your API documentation with an interactive explorer.

Multiple APIs

When you define multiple APIs, Swagger UI shows a dropdown to switch between them:

Zodra.api "/api/v1" do
  resources :products
  resources :orders
end

Zodra.api "/admin" do
  resource :dashboard, only: %i[show]
end

Each API gets its own OpenAPI spec served at /docs/specs/{slug} (e.g., /docs/specs/api-v1, /docs/specs/admin).

Configuration

Customize the OpenAPI metadata in your initializer:

Zodra.configure do |config|
  config.openapi_title = "My API"
  config.openapi_version = "2.0.0"
  config.openapi_description = "Order management API"
end

Excluding endpoints

Use openapi false in a contract to exclude it from the generated spec:

Zodra.contract :internal_metrics do
  openapi false

  action :show do
    response do
      integer :requests_per_second
      decimal :avg_response_time
    end
  end
end

This contract still works for validation and serialization but won't appear in Swagger UI.

Descriptions and deprecation

Add descriptions to actions and mark them as deprecated:

Zodra.contract :products do
  action :index do
    description "List all products with pagination"
    response :product, collection: true
  end

  action :legacy_search do
    description "Search products by name"
    deprecated!
    params do
      string? :query
    end
    response :product, collection: true
  end
end

Descriptions appear as summaries in Swagger UI. Deprecated actions are visually marked with a strikethrough.

Generating JSON specs

Export OpenAPI specs as JSON files:

rails zodra:openapi

This writes one JSON file per API to your configured output path:

app/javascript/types/
├── openapi-api-v1.json
└── openapi-admin.json

Useful for CI pipelines, external documentation tools, or API clients that consume OpenAPI specs directly.

What gets generated

Zodra maps your DSL to OpenAPI automatically: