Swaggable
Flexible swagger documentation generation tool. Allows building a Rack application that serves Swagger 2 documentation from Grape APIs.
Getting Started
# my_rack_app.rb
require 'swaggable'
api_def = Swaggable::ApiDefinition.from_grape_api(UsersApi)
rack_app = Swaggable::RackApp.new(api_definition: api_def)
Mount your rack app as swagger.json
and you can point Swagger UI to it.
Working with Grape
You can import several Grape APIs:
Swaggable::GrapeAdapter.new.import(UsersApi, api_def)
Swaggable::GrapeAdapter.new.import(CommentsApi, api_def)
You can tweak the generated ApiDefinition directly:
api_def.title = 'My Service'
api_def.description = 'Does stuff.'
api_def.endpoints['GET /users/{id}'].description = 'Show user'
api_def.endpoints['GET /users/{id}'].['Users'].description = 'Users resource'
api_def.endpoints['GET /users/{id}'].parameters['filter'].description = 'Allows filtering'
api_def.endpoints['GET /users/{id}'].responses[403].description = 'Forbidden'
It supports status codes and entities. A more complex Grape example here:
class TeamCreateEntity < Grape::Entity
def self.name
'create team payload'
end
expose :name, documentation: {
type: 'String',
desc: 'Name for the Team',
required: true,
}
end
class TeamsApi < Grape::API
format :json
content_type :json, 'application/json'
version 'v1.0', using: :path, vendor: :workshare
prefix "api"
route_param :account_uuid do
resource :teams do
desc "Creates a new team for such account"
params do
requires :account_uuid, type: String, desc: 'UUID of the account to be associated with the new team'
end
codes = default_codes + [
[201, 'Created'],
[422, 'Validations failed'],
[404, 'Account not found']
]
post(http_codes: codes, entity: TeamCreateEntity) do
## Some action here...
end
end
end
end
api_def = Swaggable::ApiDefinition.from_grape_api(TeamsApi)
rack_app = Swaggable::RackApp.new(api_definition: api_def)
Validating the resultant Swagger JSON
Validate the results against the corresponding schema in your tests:
it "validates" do
expect(rack_app.validate).to eq []
end
Working directly with the DSL
Define the API without Grape:
Swaggable::ApiDefinition.new do
version '1.0'
title 'My API'
description 'A test API'
base_path '/api/1.0'
endpoints.add_new do
path '/users/{id}'
verb :put
description 'Updates an user'
summary 'Updates attributes of such user'
.add_new do
name 'Users'
description 'Users resource'
end
parameters.add_new do
name 'include_comments_count'
description 'It will return the comments_count attribute when set to true'
location :query # [:path, :query, :header, :body, :form, nil]
required false
type :boolean # [:string, :number, :integer, :boolean, :array, :file, nil]
end
parameters.add_new do
name 'user'
description 'The new attributes for the user'
location :body
required true
schema do
name :user
attributes do
add_new do
name :first_name
type :string
end
end
end
end
responses.add_new do
status 200
description 'Success'
end
responses.add_new do
status 404
description 'User not found'
end
consumes << :json
produces << :json
end
end
TODO
- Document classes.
- Include Redirector.
- Request & response validations.
- Response body schemas.
Contributing
Do not forget to run the tests with:
bundle exec rake
And bump the version with any of:
$ gem bump --version 1.1.1 # Bump the gem version to the given version number
$ gem bump --version major # Bump the gem version to the next major level (e.g. 0.0.1 to 1.0.0)
$ gem bump --version minor # Bump the gem version to the next minor level (e.g. 0.0.1 to 0.1.0)
$ gem bump --version patch # Bump the gem version to the next patch level (e.g. 0.0.1 to 0.0.2)
License
Released under the MIT License. See the LICENSE file for further details.