README.md in fitting-2.15.0 vs README.md in fitting-2.16.0
- old
+ new
@@ -1,348 +1,130 @@
# Fitting
+Coverage API Blueprint, Swagger and OpenAPI with rspec tests for easily make high-quality API and documenatiton.
+
-[](https://badge.fury.io/rb/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.
-
## Installation
-
-First you need to install [drafter](https://github.com/apiaryio/drafter).
-
-Then add this line to your application's Gemfile:
-
+Add this line to your application's Gemfile:
```ruby
gem 'fitting'
```
After that execute:
-
```bash
$ bundle
```
Or install the gem by yourself:
-
```bash
$ gem install fitting
```
## Usage
+And next to your `spec_helper.rb`:
-Add this to your `.fitting.yml`:
-
-```yaml
-apib_path: /path/to/doc.apib
-```
-
-And this to your `spec_helper.rb`:
-
```ruby
require 'fitting'
Fitting.save_test_data
```
-The result files will be created in `./fitting_tests/` folder.
+Add this to your `.fitting.yml`:
-Output example:
+### OpenAPI 2.0
+Also Swagger
-```json
-[
- {
- "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"
- }
-]
+```yaml
+prefixes:
+ - name: /api/v1
+ openapi2_json_path: doc.json
```
-## Documentation coverage
+### OpenAPI 3.0
+Also OpenAPI
-To match routes and validate JSON-schemas run:
-
-```bash
-rake fitting:documentation_responses[report_size]
+```yaml
+prefixes:
+ - name: /api/v1
+ openapi3_yaml_path: doc.yaml
```
-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.
+### API Blueprint
+First you need to install [drafter](https://github.com/apiaryio/drafter).
+Works after conversion from API Blueprint to API Elements (in YAML file) with Drafter.
-E.g. for `xs` size:
+That is, I mean that you first need to do this
```bash
-rake fitting:documentation_responses[xs]
+drafter doc.apib -o doc.yaml
```
-**Note**: In zsh you should add quotes around the task:
+and then
-```bash
-rake 'fitting:documentation_responses[xs]'
+```yaml
+prefixes:
+ - name: /api/v1
+ drafter_yaml_path: doc.yaml
```
-Also you can use `documentation_responses_error` to get more detailed errors description.
-Check the examples below.
+### Tomograph
-### Examples
+To use additional features of the pre-converted [tomograph](https://github.com/funbox/tomograph)
-`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
-
-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).
+```yaml
+prefixes:
+ - name: /api/v1
+ tomogram_json_path: doc.json
```
-`s` size:
-
-```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
-
-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).
+## Run
+Run tests first to get run artifacts
+```bash
+bundle e rspec
```
-`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", ...}
-```
-
-### Experimental report
-
-This report will be available and properly documented in the next major update, but you already can try it by running:
-
+and then
```bash
bundle e rake fitting:report
```
-Using this you can document API prefixes.
-The task will create JSON (`fitting/report.json`) and HTML (`fitting/index.html`) reports.
+Console ouptut
-## Tests coverage
+```text
+/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
-Only `xs` size is available for tests coverage:
-
-```bash
-rake fitting:tests_responses[xs]
+tests_without_prefixes: 42
+tests_without_actions: 144
+tests_without_responses: 43
```
-## Config
+And task will create HTML (`fitting/index.html`) reports.
-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`).
+
-All the available config options are described below.
+More information on action coverage
-### `apib_path`
-
-Path to API Blueprint v3 documentation.
-There must be an installed [drafter](https://github.com/apiaryio/drafter) to parse it.
-
-### `drafter_yaml_path`
-
-Path to API Blueprint v3 documentation, pre-parsed with `drafter` and saved to a YAML file.
-
-### `drafter_4_apib_path`
-
-Path to API Blueprint v4 documentation.
-There must be an installed [drafter](https://github.com/apiaryio/drafter) to parse it.
-
-### `drafter_4_yaml_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`
-
-Path to API Blueprint v4 documentation, pre-parsed with `crafter` and saved to a YAML file.
-
-### `tomogram_json_path`
-
-Path to Tomogram documentation, pre-parsed with [tomograph](https://github.com/funbox/tomograph) and saved to a JSON file.
-
-### `strict`
-
-Default: `false`
-
-When `true` all properties are considered to have `"required": true` and all objects are considered to have `"additionalProperties": false`.
-
-### `prefix`
-
-Prefix for API requests. E.g. `'/api'`. Validation will not be performed if the request path does not start with a prefix.
-
-### `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
- /users/{id}:
- - GET
- - PATCH
- /users/{id}/employees:
- - GET
- /sessions: []
-```
-
-Empty array (`[]`) means all methods.
-
-### `resource_white_list`
-
-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
- - GET /users/{id}
- - PATCH /users/{id}
- /users/{id}/employees:
- - GET /users/{id}/employees
- /sessions: []
-```
-
-Empty array (`[]`) means all methods.
-
-### `json_schema_cover`
-
-Default: false
-
-JSON-schema covering becomes mandatory.
-However, if you don't use `Fitting.statistics` you can call `responses.statistics.cover_save`.
-
-### `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.
-The list does not affect the work of the matcher.
-It's used for the CLI report only.
-
-```yaml
-include_resources:
- - /sessions
-```
-
-### `include_actions`
-
-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.
-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`
-
-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` 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 [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.