Esplanade

This gem helps you to validate and synchronize your API in strict accordance to the documentation in API Blueprint format. To do this it automatically searches received requests and responses in the documentation and run JSON-schemas validators.

Contents

• Installation
• Usage
• Middlewares
  • Esplanade::SafeMiddleware
  • Esplanade::DangerousMiddleware
  • Esplanade::CheckCustomResponseMiddleware
• Esplanade::Error
  • Esplanade::Request::Error
    • Esplanade::Request::PrefixNotMatch
    • Esplanade::Request::NotDocumented
    • Esplanade::Request::ContentTypeIsNotJson
    • Esplanade::Request::BodyIsNotJson
    • Esplanade::Request::Invalid
  • Esplanade::Response::Error
    • Esplanade::Response::NotDocumented
    • Esplanade::Response::BodyIsNotJson
    • Esplanade::Response::Invalid
• Middleware args
  • apib_path
  • drafter_yaml_path
  • prefix
• License

Installation

Add this line to your application's Gemfile:

gem 'esplanade'

After that execute:

$ bundle

Or install the gem by yourself:

$ gem install esplanade

Usage

config/application.rb:

config.middleware.use Esplanade::SafeMiddleware, drafter_yaml_path: 'doc.yaml'

Middlewares

Esplanade::SafeMiddleware

Debug logger.

Esplanade::DangerousMiddleware

It throws errors, so you should add your own middleware for processing.

config.middleware.use YourMiddleware
config.middleware.use Esplanade::DangerousMiddleware, drafter_yaml_path: 'doc.yaml'

Esplanade::CheckCustomResponseMiddleware

Use it if you want to be sure that you have documented new custom responses.

config.middleware.use Esplanade::CheckCustomResponseMiddleware, drafter_yaml_path: 'doc.yaml'
config.middleware.use YourMiddleware
config.middleware.use Esplanade::DangerousMiddleware, drafter_yaml_path: 'doc.yaml'

Esplanade::Error

Parent class for those described below.

Esplanade::Request::Error

Parent class for those described below. Inherited from Esplanade::Error.

Esplanade::Request::PrefixNotMatch

Error message format:

{
  :method => "method",
  :path => "path",
  :raw_path => "path",
  :content_type => "content_type"
}

Esplanade::Request::NotDocumented

Error message format:

{
  :method => "method",
  :path => "path",
  :raw_path => "path",
  :content_type => "content_type"
}

Esplanade::Request::ContentTypeIsNotJson

Error message format:

{
  :method => "method",
  :path => "path",
  :raw_path => "path",
  :content_type => "content_type"
}

Esplanade::Request::BodyIsNotJson

Throws an error also when the body is empty and equal nil.

Error message format:

{
  :method => "method",
  :path => "path",
  :raw_path => "path",
  :content_type => "content_type",
  :body => "body"
}

Esplanade::Request::Invalid

Error message format:

{
  :method => "method",
  :path => "path",
  :raw_path => "path",
  :content_type => "content_type",
  :body => "body",
  :error => ["error"]
}

Esplanade::Response::Error

Parent class for those described below. Inherited from Esplanade::Error.

Esplanade::Response::NotDocumented

Error message format:

{
  :request => {
    :method => "method",
    :path => "path",
    :raw_path => "path"
  },
  :status => "status"
}

Esplanade::Response::BodyIsNotJson

It's thrown when expected response to request isn't JSON (not Content-Type: application/json) and there's no non-JSON responses documented for the endpoint.

Error message format:

{
  :request => {
    :method => "method",
    :path => "path",
    :raw_path => "path"
  },
  :status => "status",
  :body => "body"
}

Esplanade::Response::Invalid

Error message format:

{
  :request => {
    :method => "method",
    :path => "path",
    :raw_path => "path"
  },
  :status => "status",
  :body => "body",
  :error => ["error"]
}

Middleware args

Support any tomograph constructor-params

License

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