Swagger::Blocks

Swagger::Blocks is a DSL that allows you to write API documentation in pure Ruby code blocks. These blocks are then converted into JSON compatible with the Swagger 2.0 specification and Swagger UI.

Key characteristics:

• Live Updating: Changes to your Ruby code are reflected in your API docs upon refresh.
• Framework Agnostic: Works with Rails, Sinatra, or even plain Ruby objects.
• 1:1 Mapping: The DSL block names and nesting closely follow the Swagger spec structure.

Swagger 2.0

This is the primary supported version for swagger-blocks >= 2.0.0.

Swagger 1.2

Support for the Swagger 1.2 spec was dropped in version 2.0.0. If your project requires Swagger 1.2 support, you must use version 1.4.0 of the gem.

For common responses (like 401 Unauthorized or 404 Not Found), you can create a Ruby module that uses self.extended(base) to inject response blocks into an operation.

module SwaggerResponses
  module AuthenticationError
    def self.extended(base)
      base.response 401 do
        key :description, 'not authorized'
        schema do
          key :'$ref', :AuthenticationError
        end
      end
    end
  end
end

# Usage in a controller
operation :post do
  extend SwaggerResponses::AuthenticationError
end

You can pass configuration keys directly as arguments to DSL methods (like parameter) to avoid multiple key calls. This is equivalent to using the key method inside a block.

# Using inline keys
parameter paramType: :path, name: :petId, type: :string do
  key :description, 'ID of pet that needs to be fetched'
end

Instead of redefining the same parameters in multiple operations, you can define them once in the swagger_root and reference them by name within swagger_path or operation nodes.

swagger_root do
  parameter :species do
    key :name, :species
    key :description, 'Species of this pet'
  end
end

swagger_path '/pets/' do
  operation :post do
    parameter :species
  end
end

You can install swagger-blocks by adding it to your Gemfile or by installing it directly via the command line.

# In your Gemfile
gem 'swagger-blocks'

gem install swagger-blocks

You can define data models (schemas) by using swagger_schema within a class. This allows you to reference these models in your paths using '$ref'.

class Pet < ActiveRecord::Base
  include Swagger::Blocks

  swagger_schema :Pet do
    key :required, [:id, :name]
    property :id do
      key :type, :integer
      key :format, :int64
    end
    property :name do
      key :type, :string
    end
  end
end

To support API key or OAuth2 authentication, define security_definition blocks within your swagger_root. You can then apply these to the entire API or to specific operations using the security block.

# In swagger_root
security_definition :api_key do
  key :type, :apiKey
  key :name, :api_key
  key :in, :header
end

# In an operation
operation :get do
  security do
    key :api_key, []
  end
end

For examples of complex features and advanced Swagger 2.0 declarations, refer to the project's specification test file. This is the most authoritative source for seeing how nested structures and advanced schema features are implemented using swagger_blocks syntax.

https://github.com/fotinakis/swagger-blocks/blob/master/spec/lib/swagger_v2_blocks_spec.rb

Use swagger_path(path, &block) to define a Swagger Path Item object. If you call swagger_path multiple times with the same path, the library will merge the subsequent declarations into the existing path node. This allows you to spread path definitions across different parts of your code.

# First declaration
swagger_path '/users' do
  get 'Returns all users'
end

# Subsequent declaration (merges into '/users')
swagger_path '/users' do
  post 'Creates a user'
end