Swagcov

OpenAPI documentation coverage report for Rails Routes.

Usages

• See overview of different endpoints covered, missing and what you choose to ignore.
• Add pass/fail to your build pipeline when missing documentation coverage.

Usage Options

swagcov can be used with a few different approachs.
The approaches below are listed in the following order:

• via executable
• via rake task
• via rails console

View OpenAPI documentation coverage report for Rails Route endpoints

• swagcov
• rake swagcov
• Swagcov::Runner.new.run

Generate required .swagcov.yml config file

• swagcov --init
• rake swagcov -- --init
• Swagcov::Runner.new(args: ["--init"]).run

Generate optional .swagcov_todo.yml config file

• swagcov --todo
• rake swagcov -- --todo
• Swagcov::Runner.new(args: ["--todo"]).run

View swagcov version

• swagcov -v
• rake swagcov -- -v
• Swagcov::Runner.new(args: ["-v"]).run

View command line usage options

• swagcov --help
• rake swagcov -- --help
• Swagcov::Runner.new(args: ["--help"]).run

Ruby and Rails Version Support

Versioning support from a test coverage perspective, see tests.yml for detail
| ruby -v | rails 4.2 | rails 5.0 | rails 5.1 | rails 5.2 | rails 6.0 | rails 6.1 | rails 7.0 | rails 7.1 | rails 7.2 | rails 8.0 |
| — | — | — | — | — | — | — | — | — | — | — |
| 2.5 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| 2.6 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| 2.7 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| 3.0 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| 3.1 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| 3.2 | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 3.3 | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 3.4 | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 3.5 | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

Installation

Add this line to your application’s Gemfile:

gem "swagcov"

Execute:

bundle

Create a .swagcov.yml in root of your Rails application. Alternatively, run:

bundle exec rake swagcov:install

• Add the paths of your OpenAPI .yml and/or .json files (required):

  docs:
  paths:
    - swagger.yaml
    - swagger.json
  

• Add only routes (optional) :

  routes:
  paths:
    only:
      - ^/v1
  

• Add ignore routes (optional) :

  routes:
  paths:
    ignore:
      - /v1/foobar/:token
  

• Full Example .swagcov.yml Config File:

  docs:
  paths:
    - swagger.yaml
  

routes:
paths:
only:
- ^/v1
ignore:
- /v1/foobar/:token
- /v1/foobar:
- GET

Execute:
```shell
bundle exec rake swagcov

Examples

Configurations and output from running bundle exec rake swagcov from the root of your Rails Application

• All Routes (minimal configuration):

  docs:
  paths:
    - swagger.yaml
  

  

• With only endpoint configuration:

  docs:
  paths:
    - swagger.yaml
  

routes:
paths:
only:
- ^/v2

  <img src="https://raw.githubusercontent.com/smridge/swagcov/main/images/only-endpoints.png">

- With `ignore` and `only` endpoint configurations:
  ```yml
  docs:
    paths:
      - swagger.yaml

  routes:
    paths:
      only:
        - ^/v2
      ignore:
        - /v2/users
        - /v2/users/:id:
          - GET

Contributing

See CONTRIBUTING.md for detail

Credit

To @lonelyelk for initial development!

Contributors