Fitting

There are such ways of describing the API documentation as API Blueprint, Swagger and OpenAPI. And using the tests already writed for your code, you can reuse them to find out the documentation coverage. This makes it easy to find out how much the documentation matches the implementation.

• Cool if you already have a project with tests and documentation, you can check how good everything is and fix microbags.

• If are you going developing API and write documentation for it, this tool will help you document-driven development easily create high-quality write API documentation and API.

• Also, if you have an undocumented API, this is an easy way to describe it.

Installation

Add this line to your application's Gemfile:

gem 'fitting'

After that execute:

$ bundle

Or install the gem by yourself:

$ gem install fitting

Usage

And next to your spec_helper.rb:

require 'fitting'

Fitting.save_test_data

Add this to your .fitting.yml:

OpenAPI 2.0

Also Swagger

prefixes:
  - name: /api/v1
    openapi2_json_path: doc.json

OpenAPI 3.0

Also OpenAPI

prefixes:
  - name: /api/v1
    openapi3_yaml_path: doc.yaml

API Blueprint

First you need to install drafter. Works after conversion from API Blueprint to API Elements (in YAML file) with Drafter.

That is, I mean that you first need to do this

drafter doc.apib -o doc.yaml

and then

prefixes:
  - name: /api/v1
    drafter_yaml_path: doc.yaml

Tomograph

To use additional features of the pre-converted tomograph

prefixes:
  - name: /api/v1
    tomogram_json_path: doc.json

Run

Run tests first to get run artifacts

bundle e rspec

and then

bundle e rake fitting:report

Console ouptut

/api/v1
POST	/api/v1/accounts/{account_id}/inboxes				 0% 200 0% 404 0% 403
PATCH	/api/v1/accounts/{account_id}/inboxes/{id}			 0% 200 0% 404 0% 403
POST	/api/v1/accounts/{account_id}/inboxes/{id}/set_agent_bot	 0% 204 100% 404 0% 403
GET	/api/v1/agent_bots						 0% 200 0% 404 0% 403
GET	/api/v1/accounts/{account_id}/conversations			 0% 200 0% 400 0% description
POST	/api/v1/accounts/{account_id}/conversations			 0% 200 0% 403
GET	/api/v1/accounts/{account_id}/conversations/{id}		 59% 200 0% 404 0% 403
POST	/api/v1/accounts/{account_id}/conversations/{id}/toggle_status	 80% 200 0% 404 0% 403
GET	/api/v1/accounts/{account_id}/conversations/{id}/messages	 47% 200 0% 404 0% 403
POST	/api/v1/accounts/{account_id}/conversations/{id}/messages	 0% 200 0% 404 0% 403
GET	/api/v1/accounts/{account_id}/conversations/{id}/labels		 100% 200 0% 404 0% 403
POST	/api/v1/accounts/{account_id}/conversations/{id}/labels		 100% 200 0% 404 0% 403
POST	/api/v1/accounts/{account_id}/conversations/{id}/assignments	 77% 200 0% 404 0% 403
GET	/api/v1/accounts/{account_id}/contacts				 0% 200 0% 400
POST	/api/v1/accounts/{account_id}/contacts				 14% 200 0% 400
GET	/api/v1/accounts/{account_id}/contacts/{id}			 14% 200 0% 404 0% 403
PUT	/api/v1/accounts/{account_id}/contacts/{id}			 0% 204 0% 404 0% 403
GET	/api/v1/accounts/{account_id}/contacts/{id}/conversations	 0% 200 0% 404 0% 403
GET	/api/v1/accounts/{account_id}/contacts/search			 0% 200 0% 401
POST	/api/v1/accounts/{account_id}/contacts/{id}/contact_inboxes	 0% 200 0% 401 100% 422
GET	/api/v1/profile							 88% 200 100% 401

tests_without_prefixes: 42
tests_without_actions: 144
tests_without_responses: 43

And task will create HTML (fitting/index.html) reports.

More information on action coverage

prefix name

Setting the prefix name is optional. For example, you can do this:

prefixes:
  - openapi2_json_path: doc.json

prefix skip

It is not necessary to immediately describe each prefix in detail, you can only specify its name and skip it until you are ready to documented it

prefixes:
- name: /api/v1
  openapi2_json_path: doc.json
- name: /api/v3
  skip: true

Contributing

Bug reports and pull requests are welcome on GitHub at 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.

License

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