Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tuwilof/esplanade
Validate requests and responses against API Blueprint specifications
https://github.com/tuwilof/esplanade
api-blueprint drafter json-schema validation
Last synced: 6 days ago
JSON representation
Validate requests and responses against API Blueprint specifications
- Host: GitHub
- URL: https://github.com/tuwilof/esplanade
- Owner: tuwilof
- License: mit
- Created: 2017-02-06T09:38:23.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2024-04-03T20:00:21.000Z (8 months ago)
- Last Synced: 2024-08-10T21:34:06.721Z (3 months ago)
- Topics: api-blueprint, drafter, json-schema, validation
- Language: Ruby
- Homepage:
- Size: 196 KB
- Stars: 12
- Watchers: 6
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Esplanade
This gem helps you to validate and synchronize your API in strict accordance to the documentation in
[API Blueprint](https://apiblueprint.org/) and [OpenAPI](https://www.openapis.org/) formats.
To do this it automatically searches received requests and responses in the documentation and run
JSON-schemas validators.
## Contents
- [Installation](#installation)
- [Usage](#usage)
- [Middlewares](#middlewares)
- [Esplanade::SafeMiddleware](#esplanadesafemiddleware)
- [Esplanade::DangerousMiddleware](#esplanadedangerousmiddleware)
- [Esplanade::CheckCustomResponseMiddleware](#esplanadecheckcustomresponsemiddleware)
- [Esplanade::Error](#esplanadeerror)
- [Esplanade::Request::Error](#esplanaderequesterror)
- [Esplanade::Request::PrefixNotMatch](#esplanaderequestprefixnotmatch)
- [Esplanade::Request::NotDocumented](#esplanaderequestnotdocumented)
- [Esplanade::Request::ContentTypeIsNotJson](#esplanaderequestcontenttypeisnotjson)
- [Esplanade::Request::BodyIsNotJson](#esplanaderequestbodyisnotjson)
- [Esplanade::Request::Invalid](#esplanaderequestinvalid)
- [Esplanade::Response::Error](#esplanaderesponseerror)
- [Esplanade::Response::NotDocumented](#esplanaderesponsenotdocumented)
- [Esplanade::Response::BodyIsNotJson](#esplanaderesponsebodyisnotjson)
- [Esplanade::Response::Invalid](#esplanaderesponseinvalid)
- [Middleware args](#middleware-args)
- [`apib_path`](#apib_path)
- [`drafter_yaml_path`](#drafter_yaml_path)
- [`prefix`](#prefix)
- [License](#license)
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'esplanade'
```
After that execute:
```bash
$ bundle
```
Or install the gem by yourself:
```bash
$ gem install esplanade
```
## Usage
`config/application.rb`:
```ruby
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.
```ruby
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.
```ruby
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:
```ruby
{
:method => "method",
:path => "path",
:raw_path => "path",
:content_type => "content_type"
}
```
#### Esplanade::Request::NotDocumented
Error message format:
```ruby
{
:method => "method",
:path => "path",
:raw_path => "path",
:content_type => "content_type"
}
```
#### Esplanade::Request::ContentTypeIsNotJson
Error message format:
```ruby
{
: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:
```ruby
{
:method => "method",
:path => "path",
:raw_path => "path",
:content_type => "content_type",
:body => "body"
}
```
#### Esplanade::Request::Invalid
Error message format:
```ruby
{
: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:
```ruby
{
: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:
```ruby
{
:request => {
:method => "method",
:path => "path",
:raw_path => "path"
},
:status => "status",
:body => "body"
}
```
#### Esplanade::Response::Invalid
Error message format:
```ruby
{
:request => {
:method => "method",
:path => "path",
:raw_path => "path"
},
:status => "status",
:body => "body",
:error => ["error"]
}
```
## Middleware args
Support any [tomograph constructor-params](https://github.com/tuwilof/tomograph/tree/master#constructor-params)
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
[Sponsored by FunBox](https://funbox.ru)