README.md in fitting-2.13.1 vs README.md in fitting-2.14.0

- old
+ new

@@ -1,56 +1,56 @@ # Fitting -<a href="https://funbox.ru"> - <img src="https://funbox.ru/badges/sponsored_by_funbox_compact.svg" alt="Sponsored by FunBox" width=250 /> -</a> - [![Gem Version](https://badge.fury.io/rb/fitting.svg)](https://badge.fury.io/rb/fitting) [![Build Status](https://travis-ci.org/funbox/fitting.svg?branch=master)](https://travis-ci.org/funbox/fitting) This gem will help you implement your API in strict accordance to the documentation in [API Blueprint](https://apiblueprint.org/) 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. +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. ## Installation First you need to install [drafter](https://github.com/apiaryio/drafter). -Second add this line to your application's Gemfile: +Then add this line to your application's Gemfile: ```ruby gem 'fitting' ``` -And then execute: +After that execute: - $ bundle +```bash +$ bundle +``` -Or install it yourself as: +Or install the gem by yourself: - $ gem install fitting +```bash +$ gem install fitting +``` ## Usage -In your `.fitting.yml`: +Add this to your `.fitting.yml`: ```yaml apib_path: /path/to/doc.apib ``` -In your `spec_helper.rb`: +And this to your `spec_helper.rb`: ```ruby require 'fitting' Fitting.save_test_data ``` -The files will be created in ./fitting_tests/ path +The result files will be created in `./fitting_tests/` folder. -Example: +Output example: -``` +```json [ { "method": "GET", "path": "/api/v1/book", "body": {}, @@ -73,34 +73,49 @@ "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" - }, - ... + } +] ``` +## Documentation coverage -## Check documentation cover +To match routes and validate JSON-schemas run: -### xs size +```bash +rake fitting:documentation_responses[report_size] +``` -For match routes and valid json-schemas run +There are four types (or `report_size`) of reports available: + +- `xs` — the smallest report; +- `s` — includes coverage for `required` fields; +- `m` — includes coverage for `required` and `enum` fields; +- `l` — includes coverage for `required`, `enum` and `oneOf` fields. -for bash -``` +E.g. for `xs` size: + +```bash rake fitting:documentation_responses[xs] ``` -for zsh -``` +**Note**: In zsh you should add quotes around the task: + +```bash rake 'fitting:documentation_responses[xs]' ``` -You will get statistics: +Also you can use `documentation_responses_error` to get more detailed errors description. +Check the examples below. -``` +### Examples + +`xs` size: + +```text 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 @@ -120,15 +135,13 @@ API responses conforming to the blueprint: 16 (64.00% of 25). API responses with validation errors or untested: 9 (36.00% of 25). ``` -### s size +`s` size: -In addition to the previous comand, you will learn the coverage(required) json-schemas with task `rake fitting:documentation_responses[s]` - -``` +```text 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 @@ -148,84 +161,95 @@ 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]` +`documentation_responses_error[s]` example: ``` request method: GET request path: /api/v1/book response status: 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", ...} ``` -### m size +### Experimental report -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]` +This report will be available and properly documented in the next major update, but you already can try it by running: -### l size +```bash +bundle e rake fitting:report +``` -In addition to the previous comand, you will learn the coverage(oneOf) json-schemas with task `rake fitting:documentation_responses[l]` -For details `rake fitting:documentation_responses_error[l]` +Using this you can document API prefixes. +The task will create JSON (`fitting/report.json`) and HTML (`fitting/index.html`) reports. -## Check tests cover +## Tests coverage -### xs size +Only `xs` size is available for tests coverage: -`rake fitting:tests_responses[xs]` +```bash +rake fitting:tests_responses[xs] +``` ## Config -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`). +You can specify the settings either in a YAML file `.fitting.yml` or in a config. +If your project uses several prefixes, for each one you should create a separate YAML file in the folder `fitting` (`fitting/*.yml`). -### apib_path +All the available config options are described below. -Path to API Blueprint v3 documentation. There must be an installed [drafter](https://github.com/apiaryio/drafter) to parse it. +### `apib_path` -### drafter_yaml_path +Path to API Blueprint v3 documentation. +There must be an installed [drafter](https://github.com/apiaryio/drafter) to parse it. -Path to API Blueprint v3 documentation pre-parsed with `drafter` and saved to a YAML file. +### `drafter_yaml_path` -### drafter_4_apib_path +Path to API Blueprint v3 documentation, pre-parsed with `drafter` and saved to a YAML file. -Path to API Blueprint v4 documentation. There must be an installed [drafter](https://github.com/apiaryio/drafter) to parse it. +### `drafter_4_apib_path` -### drafter_4_yaml_path +Path to API Blueprint v4 documentation. +There must be an installed [drafter](https://github.com/apiaryio/drafter) to parse it. -Path to API Blueprint v4 documentation pre-parsed with `drafter` and saved to a YAML file. +### `drafter_4_yaml_path` -### crafter_apib_path +Path to API Blueprint v4 documentation, pre-parsed with `drafter` and saved to a YAML file. +### `crafter_apib_path` + Path to API Blueprint v4 documentation. -### crafter_yaml_path +### `crafter_yaml_path` -Path to API Blueprint v4 documentation pre-parsed with `crafter` and saved to a YAML file. +Path to API Blueprint v4 documentation, pre-parsed with `crafter` and saved to a YAML file. -### tomogram_json_path +### `tomogram_json_path` -Path to Tomogram documentation pre-parsed with [tomograph](https://github.com/funbox/tomograph) and saved to a JSON file. +Path to Tomogram documentation, pre-parsed with [tomograph](https://github.com/funbox/tomograph) and saved to a JSON file. -### strict +### `strict` -Default `false`. If `true` then all properties are condisidered to have `"required": true` and all objects `"additionalProperties": false`. +Default: `false` -### prefix +When `true` all properties are considered to have `"required": true` and all objects are considered to have `"additionalProperties": false`. -Prefix of API requests. Example: `'/api'`. Validation will not be performed if the request path does not start with a prefix. +### `prefix` -### white_list +Prefix for API requests. E.g. `'/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` +Default: all paths + +This is an array of paths that are mandatory for implementation. +The list does not affect the work of the matcher. +It's used for the CLI report only. + ```yaml white_list: /users: - DELETE - POST @@ -235,18 +259,20 @@ /users/{id}/employees: - GET /sessions: [] ``` -Empty array `[]` means all methods. +Empty array (`[]`) means all methods. -### resource_white_list +### `resource_white_list` -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. +Default: all resources +This is an array of resources that are mandatory for implementation. +The list does not affect the work of the matcher. +It's used for the CLI report only. + ```yaml resource_white_list: /users: - DELETE /users/{id} - POST /users @@ -255,59 +281,76 @@ /users/{id}/employees: - GET /users/{id}/employees /sessions: [] ``` -Empty array `[]` means all methods. +Empty array (`[]`) means all methods. -### json_schema_cover +### `json_schema_cover` -Default: false. Json-schema covering becomes mandatory. -Or you can call `responses.statistics.cover_save` if you don't use call `Fitting.statistics`. +Default: false -### include_resources +JSON-schema covering becomes mandatory. +However, if you don't use `Fitting.statistics` you can call `responses.statistics.cover_save`. -Default: all resources if `include_resources` and `include_actions` is not used. +### `include_resources` + +Default: all resources (but only when `include_resources` and `include_actions` are not defined) + 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. +The list does not affect the work of the matcher. +It's used for the CLI report only. ```yaml include_resources: - /sessions ``` -### include_actions +### `include_actions` -Default: all paths if `include_resources` and `include_actions` is not used. +Default: all paths (but only when `include_resources` and `include_actions` are not defined) + 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. +The list does not affect the work of the matcher. +It's used for the CLI report only. ```yaml include_actions: - DELETE /users/{id} - POST /users - GET /users/{id} - PATCH /users/{id} - GET /users/{id}/employees ``` -### ignore_list +### `ignore_list` -You can use ignore list for omit checks with matchers. +You can use ignore list to omit checks with matchers. ```yaml ignore_list: - %r{/api/v1/users/[1-9].} - %r{/api/v1/comments} ``` -It works only for match_schema (NOT FOR strictly_match_schema) +It works only for `match_schema` and **not** for `strictly_match_schema`. +### `prefixes` + +Example: + +```yaml +prefixes: + - name: /api/v1 + - name: /api/v2 +``` + ## Contributing -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](http://contributor-covenant.org) code of conduct. +Bug reports and pull requests are welcome on GitHub at [github.com/funbox/fitting](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](http://contributor-covenant.org) code of conduct. ## 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/badges/sponsored_by_funbox_centered.svg)](https://funbox.ru)