Documentation UIs
Docit ships with two documentation UIs, both reading from the same OpenAPI spec.
Available routes
| Path | UI | Notes |
|---|---|---|
/api-docs | Default (Scalar) | Configurable via config.default_ui |
/api-docs/scalar | Scalar API Reference | Modern UI with built-in API client, dark mode, code samples |
/api-docs/swagger | Swagger UI | Classic OpenAPI explorer |
/api-docs/system | System Map | Architecture graph with draggable nodes, manual arrows, selected-node AI guidance, and PNG export |
/api-docs/system.json | System Graph JSON | Machine-readable graph payload for exports and internal tooling |
/api-docs/spec | Raw JSON | OpenAPI 3.0.3 spec for code generation or external tools |
Scalar, Swagger, and System Map include a navigation bar to switch between them.
Changing the default UI
Set config.default_ui = :swagger to make Swagger UI the default at /api-docs:
Docit.configure do |config|
config.default_ui = :swagger
endMounting at a different path
In config/routes.rb, change the mount path:
mount Docit::Engine => "/docs" # now at /docs instead of /api-docsAll sub-routes (/docs/scalar, /docs/swagger, /docs/system, /docs/system.json, /docs/spec) follow automatically.
Raw JSON spec
If you just want the raw OpenAPI JSON (e.g., for client code generation or external tools):
GET /api-docs/specThis returns the full OpenAPI 3.0.3 JSON document.
Scalar features
The Scalar API Reference (default) includes:
- Built-in API client — test endpoints directly from the docs
- Dark mode by default
- Auto-generated code samples in Shell, Ruby, Node.js, PHP, Python, and more
- Search across all endpoints
- Clean, modern design
Swagger UI features
Swagger UI is the classic OpenAPI explorer:
- Try-it-out functionality for all endpoints
- Expandable request/response schemas
- Authorization flow support
- Widely recognized by API developers