Swagger::Blocks is a DSL for pure Ruby code blocks that can be turned into JSON.
It helps you write API docs in the Swagger style in Ruby and then automatically build JSON that is compatible with Swagger UI.
- Supports live updating by design. Change code, refresh your API docs.
- Works with all Ruby web frameworks including Rails, Sinatra, etc.
- 100% support for all features of the Swagger 1.2 spec.
- Flexible—you can use Swagger::Blocks anywhere, split up blocks to fit your style preferences, etc. Since it's pure Ruby and serves definitions dynamically, you can easily use initializers/config objects to change values or even show/hide different APIs based on environment.
- 1:1 naming with the Swagger spec—block names and nesting should match almost exactly with the swagger spec, with rare exceptions to make things more convenient.
Add this line to your application's Gemfile:
gem 'swagger-blocks'
Or install directly with gem install swagger-blocks. Requires Ruby 2.1+
This is a simplified example based on the objects in the Petstore Swagger Sample App. For a more complex and complete example, see the swagger_blocks_spec.rb file.
Also note that Rails is not required, you can use Swagger::Blocks with any Ruby web framework.
Parameters and features below are defined by the Swagger 1.2 spec.
class PetsController < ActionController::Base
include Swagger::Blocks
swagger_api_root :pets do
key :swaggerVersion, '1.2'
key :apiVersion, '1.0.0'
key :basePath, 'http://petstore.swagger.wordnik.com/api'
key :resourcePath, '/pets'
api do
key :path, '/pets/{petId}'
operation do
key :method, 'GET'
key :summary, 'Find pet by ID'
key :notes, 'Returns a pet based on ID'
key :type, :Pet
key :nickname, :getPetById
parameter do
key :paramType, :path
key :name, :petId
key :description, 'ID of pet that needs to be fetched'
key :required, true
key :type, :integer
end
response_message do
key :code, 400
key :message, 'Invalid ID supplied'
end
response_message do
key :code, 404
key :message, 'Pet not found'
end
end
end
end
# ...
endclass Pet < ActiveRecord::Base
include Swagger::Blocks
swagger_model :Pet do
key :id, :Pet
key :required, [:id, :name]
property :id do
key :type, :integer
key :format, :int64
key :description, 'unique identifier for the pet'
key :minimum, '0.0'
key :maximum, '100.0'
end
property :name do
key :type, :string
end
property :photoUrls do
key :type, :array
items do
key :type, :string
end
end
property :status do
key :type, :string
key :description, 'pet status in the store'
key :enum, [:available, :pending, :sold]
end
end
# ...
endTo integrate these definitions with Swagger UI, we need a docs controller that can serve the JSON definitions.
resources :apidocs, only: [:index, :show]class ApidocsController < ActionController::Base
swagger_root do
key :swaggerVersion, '1.2'
key :apiVersion, '1.0.0'
info do
key :title, 'Swagger Sample App'
end
api do
key :path, '/pets'
key :description, 'Operations about pets'
end
end
# A list of all classes that have swagger_* declarations.
SWAGGERED_CLASSES = [
PetsController,
Pets,
self,
].freeze
def index
render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
end
def show
render json: Swagger::Blocks.build_api_json(params[:id], SWAGGERED_CLASSES)
end
endThe special part of this controller are these lines:
render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)render json: Swagger::Blocks.build_api_json(params[:id], SWAGGERED_CLASSES)Those are the only lines necessary to build the root Swagger Resource Listing JSON and the JSON for each Swagger API Declaration. You simply pass in a list of all the "swaggered" classes in your app.
Now, simply point Swagger UI at /apidocs and everything should Just Work™. If you change any of the Swagger block definitions, you can simply refresh Swagger UI to see the changes.
See the swagger_blocks_spec.rb for examples of more complex features and declarations possible.
- Fork it ( https://github.com/fotinakis/swagger-blocks/fork )
- 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 a new Pull Request
Original idea inspired by @richhollis's swagger-docs gem.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent