Swagcov

OpenAPI documentation coverage report for Rails Routes.

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

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

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

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

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

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

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

The following default environment variables are automatically set (and can optionally be changed to your needs)

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

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

Versioning support from a test coverage perspective, see tests.yml for detail

• 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
  

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

  

• With ignore and only endpoint configurations:

  docs:
    paths:
      - swagger.yaml
  
  routes:
    paths:
      only:
        - ^/v2
      ignore:
        - /v2/users
        - /v2/users/:id:
          - GET

  

See CONTRIBUTING.md for detail

To @lonelyelk for initial development!