Configuration

All Docit configuration lives in config/initializers/docit.rb. Here's a complete reference of every option.

Basic metadata

Docit.configure do |config|
  config.title       = "My API"
  config.version     = "1.0.0"
  config.description = "Backend API documentation"
end

These map directly to the OpenAPI info object and appear at the top of your documentation UI.

Documentation UI

config.default_ui = :scalar    # :scalar (default) or :swagger

Controls which UI renders at the root /api-docs path. Both UIs are always available at their direct paths regardless of this setting.

Authentication schemes

Add one or multiple auth schemes. These appear in the OpenAPI securitySchemes component.

# Bearer token (JWT by default)
config.auth :bearer

# HTTP Basic
config.auth :basic

# API key in header
config.auth :api_key, name: "X-API-Key", location: "header"

Reference them in endpoint docs with security :bearer_auth, security :basic_auth, or security :api_key_auth.

Tag descriptions

Tags group your endpoints in the sidebar. Add descriptions to explain each group:

config.tag "Users", description: "User account management"
config.tag "Auth",  description: "Authentication endpoints"
config.tag "Admin"  # description is optional

Server URLs

Add server URLs shown in the server dropdown of the documentation UI:

config.server "https://api.example.com", description: "Production"
config.server "https://staging.example.com", description: "Staging"
config.server "http://localhost:3000", description: "Development"

License information

Add license info to the OpenAPI spec's info.license field:

config.license name: "MIT", url: "https://opensource.org/licenses/MIT"

The url parameter is optional.

Contact information

Add contact info to the OpenAPI spec's info.contact field:

config.contact name: "API Team",
              email: "api@example.com",
              url: "https://example.com/support"

All parameters are optional — include whichever you need.

Terms of service

config.terms_of_service "https://example.com/tos"

Full example

Docit.configure do |config|
  config.title       = "My API"
  config.version     = "1.0.0"
  config.description = "Backend API documentation"
  config.default_ui  = :scalar

  config.auth :bearer
  config.auth :api_key, name: "X-API-Key", location: "header"

  config.tag "Users", description: "User account management"
  config.tag "Auth",  description: "Authentication endpoints"

  config.server "https://api.example.com", description: "Production"
  config.server "http://localhost:3000", description: "Development"

  config.license name: "MIT", url: "https://opensource.org/licenses/MIT"
  config.contact name: "API Team", email: "api@example.com"
  config.terms_of_service "https://example.com/tos"
end