EasySwaggerUi

Mountable Rails plugin that serve your API documentation written in YAML files via Swagger UI.

Test against Rails 5.x. Should also work with Rails 4.2.x.

Swagger UI version: 2.2.10. Accessible by in EasySwaggerUi::SWAGGER_UI_VERSION.

Features

• Parse API documentation in YAML files and serve as JSON to be consumed by Swagger UI
• separate your documentation into multiple YAML files for ease of management
• Support using ERB in YAML files
• Serve Swagger UI

Installation

Add this line to your application's Gemfile:

gem 'easy_swagger_ui', '~> 0.1'

And then execute:

$ bundle

Usage

Mount

Mount it in config/routes.rb:

# Change the mount point as you like
mount EasySwaggerUi::Engine => 'docs'

Write your API documentation

Your documentation should match the requirement of Swagger Specification. See examples at Swagger Online Editor.

Place them under EasySwaggerUi.base_path (default to <Rails.root>/doc).

1. You should have a swagger.yml file in your documentation path.
2. You can extract something from swagger.yml into separate YAML file or into sub directories. See example in test/dummy/doc.
3. If you have multiple versions of documentation, you can place each version in a sub directory under EasySwaggerUi.base_path. Just make sure each version has a swagger.yml file.

Visit Swagger UI

You can visit Swagger UI at http://localhost:3000/docs.

If you place documentation in sub directories, append the name of sub directory into the URL.

Configuration

Create an initializer, such as config/initializers/easy_swagger_ui.rb:

EasySwaggerUi.configure do |config|
  config.base_path = Rails.root.join('doc', 'api')
end

Supported configuration options:

• base_path: String or Pathname. Base path of your documentation. Absolute path or relative path relative to Rails.root. Default to Rails.root.join('doc').
• cache_enabled: Boolean. Whether or not to cache parsing result of YAML files. Default to !Rails.env.development?
• cache_timeout: ActiveSupport::Duration. How long should cache be valid. Default to 30.minutes
• cache_store: ActiveSupport::Cache::Store. What cache store to use. Default to ActiveSupport::Cache::MemoryStore.new
• validator_enabled: Boolean. Whether or not validate swagger specification. Default to false.

License

The gem is available as open source under the terms of the MIT License.