Fitting

Optimizt avatar: OK sign with Mona Lisa picture between the fingers

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.

exmaple

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
    type: openapi2
    schema_paths:
      - doc.json

OpenAPI 3.0

Also OpenAPI

prefixes:
  - name: /api/v1
    type: openapi3
    schema_paths:
      - 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
    type: drafter
    schema_paths:
      - doc.yaml

Tomograph

To use additional features of the pre-converted tomograph

prefixes:
  - name: /api/v1
    type: tomogram
    schema_paths:
      - doc.json

Run

Run tests first to get run artifacts

bundle e rspec

and then

bundle e rake fitting:report

Run tests by outgoing request first to get run artifacts

bundle e rake fitting_out: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.

exmaple

More information on action coverage

exmaple2

prefix name

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

prefixes:
  - type: openapi2
    schema_paths:
      - 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
  type: openapi2
  schema_paths:
    - doc.json
- name: /api/v3
  skip: true

For work with WebMock outgoing request, you should set up outgoing prefixes

outgoing_prefixes:
- name: /api/v1
  type: openapi2
  schema_paths:
    - doc.json
- name: /api/v3
  skip: true

You can choose location that must be teste

prefixes:
  - type: openapi2
    schema_paths:
      - doc.json
    only:
      - POST /api/v1/users
      - GET /api/v1/user/{id}

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.

Sponsored by FunBox