Include redoc as Rails engine and document your API with simple YAML files. Supports API documentation versioning.
Add to Gemfile
gem 'api_doc_server'
And then run:
$ bundle
Add to your config/routes.rb
mount ApiDocServer::Engine, at: "/api_docs"
You can place this route under admin_constraint
or other restricted path, or configure basic HTTP authentication.
authenticate :user, lambda { |u| u.admin? } do
mount ApiDocServer::Engine, at: "/api_docs"
end
Set admin username and password in an initializer:
# config/initializers/api_doc_server.rb
ApiDocServer.configure do |config|
config.authentication_proc = proc
authenticate_or_request_with_http_basic do |username, password|
User.find_by(name: username, password: password)
end
end
end
Set the path of your json/yaml versioned documentations in an initializer:
# config/initializers/api_doc_server.rb
ApiDocServer.configure do |config|
config.swagger_urls = {
v1: 'api/v1/swagger.yaml',
v2: 'api/v2/swagger.yaml',
}
end
and place your main documentation file under /public/api
path.
# config/initializers/api_doc_server.rb
ApiDocServer.configure do |config|
config.swagger_urls = { v1: 'api/v1/swagger.yaml' }
end
Config Name | Swagger parameter name | Description |
---|---|---|
config.swagger_url | Hash<version_key,url> | The url pointing swagger.yaml (Swagger 2.0) as per OpenAPI Spec. This params requires hash value - pass your API doc version name as a key and it's main documentation url as a value. |
config.doc_config | Hash<config_attribute,value> | Any of the configs specified in https://github.com/Rebilly/ReDoc#redoc-tag-attributes, e.g. { 'scroll-y-offset': 50 } |
config.authentication_proc = | proc | a proc that takes the current controller as an argument and halts rendering per custom strategy. |
This project is available under MIT-LICENSE. ☀️