Generates swagger-ui json files for rails apps with APIs. You add the swagger DSL to your controller classes and then run one rake task to generate the json files.
Here is an extract of the DSL from a user controller API class:
swagger_controller :users, "User Management"
swagger_api :index do
summary "Fetches all User items"
param :query, :page, :integer, :optional, "Page number"
response :unauthorized
response :not_acceptable
response :requested_range_not_satisfiable
endAdd this line to your application's Gemfile:
gem 'swagger-docs'
And then execute:
$ bundle
Or install it yourself as:
$ gem install swagger-docs
Create an initializer in config/initializers (e.g. swagger_docs.rb) and define your APIs:
Swagger::Docs::Config.register_apis({
"1.0" => {
# the extension used for the API
:api_extension_type => :json,
# the output location where your .json files are written to
:api_file_path => "public/api/v1/",
# the URL base path to your API
:base_path => "http://api.somedomain.com",
# if you want to delete all .json files at each generation
:clean_directory => false
}
})The following table shows all the current configuration options and their defaults. The default will be used if you don't supply your own value.
| Option | Description | Default |
|---|---|---|
| api_extension_type | The extension, if necessary, used for your API - e.g. :json or :xml | nil |
| api_file_path | The output file path where generated swagger-docs files are written to. | public/ |
| base_path | The URI base path for your API - e.g. api.somedomain.com | / |
| base_api_controller | The base controller class your project uses; it or its subclasses will be where you call swagger_controller and swagger_api. | ActionController::Base |
| clean_directory | When generating swagger-docs files this option specifies if the api_file_path should be cleaned first. This means that all files will be deleted in the output directory first before any files are generated. | false |
| formatting | Specifies which formatting method to apply to the JSON that is written. Available options: :none, :pretty | :pretty |
class Api::V1::UsersController < ApplicationController
swagger_controller :users, "User Management"
swagger_api :index do
summary "Fetches all User items"
param :query, :page, :integer, :optional, "Page number"
param :path, :nested_id, :integer, :optional, "Team Id"
response :unauthorized
response :not_acceptable, "The request you made is not acceptable"
response :requested_range_not_satisfiable
end
swagger_api :show do
summary "Fetches a single User item"
param :path, :id, :integer, :optional, "User Id"
response :unauthorized
response :not_acceptable
response :not_found
end
swagger_api :create do
summary "Creates a new User"
param :form, :first_name, :string, :required, "First name"
param :form, :last_name, :string, :required, "Last name"
param :form, :email, :string, :required, "Email address"
param_list :form, :role, :string, :required, "Role", [ "admin", "superadmin", "user" ]
response :unauthorized
response :not_acceptable
end
swagger_api :update do
summary "Updates an existing User"
param :path, :id, :integer, :required, "User Id"
param :form, :first_name, :string, :optional, "First name"
param :form, :last_name, :string, :optional, "Last name"
param :form, :email, :string, :optional, "Email address"
param :form, :tag, :Tag, :required, "Tag object"
response :unauthorized
response :not_found
response :not_acceptable
end
swagger_api :destroy do
summary "Deletes an existing User item"
param :path, :id, :integer, :optional, "User Id"
response :unauthorized
response :not_found
end
# Support for Swagger complex types:
# https://github.com/wordnik/swagger-core/wiki/Datatypes#wiki-complex-types
swagger_model :Tag do
description "A Tag object."
property :id, :integer, :required, "User Id"
property :name, :string, :optional, "Name"
end
endSuppose you have a header or a parameter that must be present on several controllers and methods. Instead of duplicating it on all the controllers you can do this on your API base controller:
class Api::BaseController < ActionController::Base
class << self
Swagger::Docs::Generator::set_real_methods
def inherited(subclass)
super
subclass.class_eval do
setup_basic_api_documentation
end
end
private
def setup_basic_api_documentation
[:index, :show, :create, :update, :delete].each do |api_action|
swagger_api api_action do
param :header, 'Authentication-Token', :string, :required, 'Authentication token'
end
end
end
end
endAnd then use it as a superclass to all you API controllers. All the subclassed controllers will have the same documentation applied to them.
| Method | Description |
|---|---|
| summary | The summary of the API |
| param | Standard API Parameter |
| param_list | Standard API Enum/List parameter. |
| response | Takes a symbol or status code and passes it to `Rack::Utils.status_code`. The current list of status codes can be seen here: https://github.com/rack/rack/blob/master/lib/rack/utils.rb. An optional message can be added. |
rake swagger:docs
Swagger-ui JSON files should now be present in your api_file_path (e.g. ./public/api/v1)
A sample Rails application where you can run the above rake command and view the output in swagger-ui can be found here:
https://github.com/richhollis/swagger-docs-sample
By default swagger-docs is applied to controllers inheriting from ApplicationController. If this is not the case for your application, use this snippet in your initializer before calling Swagger::Docs::Config#register_apis(...).
class Swagger::Docs::Config
def self.base_api_controller; Api::ApiController end
endBy default, swagger-docs finds controllers by traversing routes in Rails.application.
To override this, you can customize the base_application config in an initializer:
class Swagger::Docs::Config
def self.base_application; Api::Engine end
endSwagger allows a distinction between the API documentation server and the hosted API
server through the path variable (see Swagger: No server Integrations). To override the default swagger-docs behavior, you can provide a transform_path
class method in your initializer:
class Swagger::Docs::Config
def self.transform_path(path)
"http://example.com/api-docs/#{path}"
end
endThe transformation will be applied to all API path values in the generated api-docs.json file.
It is best-practice not to keep documentation in version control. An easy way to integrate swagger-docs into a conventional deployment setup (e.g. capistrano, chef, or opsworks) is to piggyback on the 'assets:precompile' rake task. And don't forget to add your api documentation directory to .gitignore in this case.
#Rakefile or lib/task/precompile_overrides.rake
namespace :assets do
task :precompile do
Rake::Task['assets:precompile'].invoke
Rake::Task['swagger:docs'].invoke
end
endapi-docs.json output:
{
"apiVersion": "1.0",
"swaggerVersion": "1.2",
"basePath": "/api/v1",
"apis": [
{
"path": "/users.{format}",
"description": "User Management"
}
]
}users.json output:
{
"apiVersion": "1.0",
"swaggerVersion": "1.2",
"basePath": "http://api.somedomain.com/api/v1/",
"resourcePath": "/users",
"apis": [
{
"path": "/users",
"operations": [
{
"summary": "Fetches all User items",
"parameters": [
{
"paramType": "query",
"name": "page",
"type": "integer",
"description": "Page number",
"required": false
}
],
"responseMessages": [
{
"code": 401,
"message": "Unauthorized"
},
{
"code": 406,
"message": "The request you made is not acceptable"
},
{
"code": 416,
"message": "Requested Range Not Satisfiable"
}
],
"method": "get",
"nickname": "Api::V1::Users#index"
}
]
},
{
"path": "nested/{nested_id}/sample",
"operations": [
{
"summary": "Fetches all User items",
"parameters": [
{
"paramType": "query",
"name": "page",
"type": "integer",
"description": "Page number",
"required": false
},
{
"paramType": "path",
"name": "nested_id",
"type": "integer",
"description": "Team Id",
"required": false
}
],
"responseMessages": [
{
"code": 401,
"message": "Unauthorized"
},
{
"code": 406,
"message": "The request you made is not acceptable"
},
{
"code": 416,
"message": "Requested Range Not Satisfiable"
}
],
"method": "get",
"nickname": "Api::V1::Users#index"
}
]
},
{
"path": "/users",
"operations": [
{
"summary": "Creates a new User",
"parameters": [
{
"paramType": "form",
"name": "first_name",
"type": "string",
"description": "First name",
"required": true
},
{
"paramType": "form",
"name": "last_name",
"type": "string",
"description": "Last name",
"required": true
},
{
"paramType": "form",
"name": "email",
"type": "string",
"description": "Email address",
"required": true
}
],
"responseMessages": [
{
"code": 401,
"message": "Unauthorized"
},
{
"code": 406,
"message": "Not Acceptable"
}
],
"method": "post",
"nickname": "Api::V1::Users#create"
}
]
},
{
"path": "/users/{id}",
"operations": [
{
"summary": "Fetches a single User item",
"parameters": [
{
"paramType": "path",
"name": "id",
"type": "integer",
"description": "User Id",
"required": false
}
],
"responseMessages": [
{
"code": 401,
"message": "Unauthorized"
},
{
"code": 404,
"message": "Not Found"
},
{
"code": 406,
"message": "Not Acceptable"
}
],
"method": "get",
"nickname": "Api::V1::Users#show"
}
]
},
{
"path": "/users/{id}",
"operations": [
{
"summary": "Updates an existing User",
"parameters": [
{
"paramType": "path",
"name": "id",
"type": "integer",
"description": "User Id",
"required": true
},
{
"paramType": "form",
"name": "first_name",
"type": "string",
"description": "First name",
"required": false
},
{
"paramType": "form",
"name": "last_name",
"type": "string",
"description": "Last name",
"required": false
},
{
"paramType": "form",
"name": "email",
"type": "string",
"description": "Email address",
"required": false
},
{
"paramType": "form",
"name": "tag",
"type": "Tag",
"description": "Tag object",
"required": true
}
],
"responseMessages": [
{
"code": 401,
"message": "Unauthorized"
},
{
"code": 404,
"message": "Not Found"
},
{
"code": 406,
"message": "Not Acceptable"
}
],
"method": "put",
"nickname": "Api::V1::Users#update"
}
]
},
{
"path": "/users/{id}",
"operations": [
{
"summary": "Deletes an existing User item",
"parameters": [
{
"paramType": "path",
"name": "id",
"type": "integer",
"description": "User Id",
"required": false
}
],
"responseMessages": [
{
"code": 401,
"message": "Unauthorized"
},
{
"code": 404,
"message": "Not Found"
}
],
"method": "delete",
"nickname": "Api::V1::Users#destroy"
}
]
}
],
"models": {
"Tag": {
"id": "Tag",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer",
"description": "User Id"
},
"name": {
"type": "string",
"description": "Name",
"foo": "test"
}
},
"description": "A Tag object."
}
}
}Thanks to jdar, fotinakis, stevschmid, ldnunes and all of our contributors for making swagger-docs even better.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request