This gem will help you implement your API in strict accordance to the documentation in API Blueprint format. To do this, when you run your RSpec tests on controllers, it automatically searches for the corresponding json-schemas in the documentation and then validates responses with them.

Add this line to your application's Gemfile:

gem 'fitting'

And then execute:

$ bundle

Or install it yourself as:

$ gem install fitting

In your .fitting.yml:

apib_path: /path/to/doc.apib

In your spec_helper.rb:

require 'fitting'

Fitting.save_test_data

The tests.json file will be created

Example:

[
  {
    "method": "GET",
    "path": "/api/v1/book",
    "body": {},
    "response": {
      "status": 200,
      "body": {
        "title": "The Martian Chronicles"
      }
    },
    "title": "/spec/controllers/api/v1/books_controller_spec.rb:11",
    "group": "/spec/controllers/api/v1/books_controller_spec.rb"
  },
  {
    "method": "POST",
    "path": "/api/v1/book",
    "body": {},
    "response": {
      "status": 200,
      "body": {
        "title": "The Old Man and the Sea"
      }
    },
    "title": "/spec/controllers/api/v1/books_controller_spec.rb:22",
    "group": "/spec/controllers/api/v1/books_controller_spec.rb"
  },
  ...

For match routes and valid json-schemas run rake fitting:documentation_responses[xs]

You will get statistics:

Fully conforming requests:
DELETE  /api/v1/book                 ✔ 200 ✔ 201 ✔ 404
DELETE  /api/v1/book/{id}            ✔ 200 ✔ 201 ✔ 404
GET     /api/v1/book/{id}/seller     ✔ 200 ✔ 201 ✔ 404

Partially conforming requests:
GET     /api/v1/book                 ✖ 200 ✔ 404
POST    /api/v1/book                 ✖ 200 ✔ 201 ✔ 404
GET     /api/v1/book/{id}            ✖ 200 ✔ 404 ✔ 200
PATCH   /api/v1/book/{id}            ✖ 200 ✔ 201 ✔ 404

Non-conforming requests:
GET     /api/v1/seller               ✖ 200 ✖ 201 ✖ 404
GET     /api/v1/buyer                ✖ 200 ✖ 404

API requests with fully implemented responses: 3 (33.33% of 9).
API requests with partially implemented responses: 4 (44.44% of 9).
API requests with no implemented responses: 2 (22.22% of 9).

API responses conforming to the blueprint: 16 (64.00% of 25).
API responses with validation errors or untested: 9 (36.00% of 25).

In addition to the previous comand, you will learn the coverage(required) json-schemas with task rake fitting:documentation_responses[s]

Fully conforming requests:
DELETE  /api/v1/book                 100% 200 100% 201 100% 404
DELETE  /api/v1/book/{id}            100% 200 100% 201 100% 404
GET     /api/v1/book/{id}/seller     100% 200 100% 201 100% 404

Partially conforming requests:
GET     /api/v1/book                 0% 200 66% 404
POST    /api/v1/book                 0% 200 90% 201 100% 404
GET     /api/v1/book/{id}            0% 200 88% 404 10% 200
PATCH   /api/v1/book/{id}            0% 200 100% 201 10% 404

Non-conforming requests:
GET     /api/v1/seller               0% 200 0% 201 0 404
GET     /api/v1/buyer                0% 200 0% 404

API requests with fully implemented responses: 3 (33.33% of 9).
API requests with partially implemented responses: 4 (44.44% of 9).
API requests with no implemented responses: 2 (22.22% of 9).

API responses conforming to the blueprint: 16 (64.00% of 25).
API responses with validation errors or untested: 9 (36.00% of 25).

For details rake fitting:documentation_responses_error[s]

request metohd: GET
request path: /api/v1/book
response staus: 200
source json-schema: {"$schema"=>"http://json-schema.org/draft-04/schema#", "type"=>"object", ...}
combination: ["required", "pages"]
new json-schema: {"$schema"=>"http://json-schema.org/draft-04/schema#", "type"=>"object", ...}

In addition to the previous comand, you will learn the coverage(enum) json-schemas with task rake fitting:documentation_responses[m] For details rake fitting:documentation_responses_error[m]

rake fitting:tests_responses[xs]

You can specify the settings either in a yaml file .fitting.yml or in config. If your project uses several prefixes, for each one you need to create a separate yaml file in the folder fitting (fitting/*.yml).

Path to API Blueprint documentation. There must be an installed drafter to parse it.

Path to API Blueprint documentation pre-parsed with drafter and saved to a YAML file.

Path to Tomogram documentation pre-parsed with tomograph and saved to a JSON file.

Default false. If true then all properties are condisidered to have "required": true and all objects "additionalProperties": false.

Prefix of API requests. Example: '/api'. Validation will not be performed if the request path does not start with a prefix.

Default: all paths. This is an array of paths that are mandatory for implementation. This list does not affect the work of the matcher. This list is only for the report in the console.

white_list:
  /users:
    - DELETE
    - POST
  /users/{id}:
    - GET
    - PATCH
  /users/{id}/employees:
    - GET
  /sessions: []

Empty array [] means all methods.

Default: all resources. This is an array of resources that are mandatory for implementation. This list does not affect the work of the matcher. This list is only for the report in the console.

resource_white_list:
  /users:
    - DELETE /users/{id}
    - POST /users
    - GET /users/{id}
    - PATCH /users/{id}
  /users/{id}/employees:
    - GET /users/{id}/employees
  /sessions: []

Empty array [] means all methods.

Default: false. Json-schema covering becomes mandatory. Or you can call responses.statistics.cover_save if you don't use call Fitting.statistics.

Default: all resources if include_resources and include_actions is not used. This is an array of resources that are mandatory for implementation. This list does not affect the work of the matcher. This list is only for the report in the console.

include_resources:
  - /sessions

Default: all paths if include_resources and include_actions is not used. This is an array of paths that are mandatory for implementation. This list does not affect the work of the matcher. This list is only for the report in the console.

include_actions:
  - DELETE /users/{id}
  - POST /users
  - GET /users/{id}
  - PATCH /users/{id}
  - GET /users/{id}/employees

You can use ignore list for omit checks with matchers.

ignore_list:
  - %r{/api/v1/users/[1-9].}
  - %r{/api/v1/comments}

It works only for match_schema (NOT FOR strictly_match_schema)

Bug reports and pull requests are welcome on GitHub at https://github.com/funbox/fitting. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

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