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

Environment Variables

The following default environment variables are automatically set (and can optionally be changed to your needs)
| Key | Value |
| :— | :— |
| SWAGCOV_DOTFILE | .swagcov.yml |
| SWAGCOV_TODOFILE | .swagcov_todo.yml |

For example SWAGCOV_DOTFILE=".openapi_coverage_config.yml" bundle exec swagcov

Exit Codes

swagcov exits with the following status codes:

• 0 - (success) if no missing documentation coverage is detected
• 1 - (offenses) if missing documentation coverage is detected
• 2 - (error) if abnormal termination due to invalid configuration, cli options, or an internal error

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 install to install the gem

• Generate the required .swagcov.yml configuration file in the root of your Rails application by executing one of the following commands:

  bundle exec swagcov --init
  bundle exec rake swagcov -- --init
  

You should now see the following file to configure to your needs:

  ## Required field:
  # List your OpenAPI documentation file(s) (accepts json or yaml)
  docs:
    paths:
      - swagger.yaml
      - swagger.json

  ## Optional fields:
  # routes:
  #   paths:
  #     only:
  #       - ^/v2 # only track v2 endpoints
  #     ignore:
  #       - /v2/users # do not track certain endpoints
  #       - /v2/users/:id: # ignore only certain actions (verbs)
  #         - GET

• Execute one of the following commands: bundle exec swagcov bundle exec rake swagcov

Example Output:

       GET /articles         200
     PATCH /articles/:id     200
    DELETE /articles/:id     204
       GET /users            200
      POST /users            201
       GET /users/:id        200
       PUT /users/:id        200
    DELETE /users/:id        204
       GET /v1/articles      200
      POST /v1/articles      201
       GET /v1/articles/:id  200
     PATCH /v1/articles/:id  200
       PUT /v1/articles/:id  200
    DELETE /v1/articles/:id  204
       GET /v2/articles      200
      POST /v2/articles      201
     PATCH /v2/articles/:id  200
    DELETE /v2/articles/:id  204
       GET /v2/articles/:id  ignored
       PUT /v2/articles/:id  ignored
      POST /articles         none
       GET /articles/:id     none
       PUT /articles/:id     none
     PATCH /users/:id        none

  OpenAPI documentation coverage 81.82% (18/22)
  2 ignored endpoints
  22 total endpoints
  18 covered endpoints
  4 uncovered endpoints

• Optionally generate a .swagcov_todo.yml config file acting as a TODO list bundle exec swagcov --todo bundle exec rake swagcov -- --todo

Examples

Configurations and output from running swagcov / 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