Swagcov

See 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.

Installation

Add this line to your application's Gemfile:

gem "swagcov"

Execute:

bundle

Create a .swagcov.yml in root of your Rails application.

• Add the paths of your openapi yml files (required):

  docs:
  paths:
    - swagger.yaml
  

• 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

Execute:
```shell
bundle exec rake swagcov

Example 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

Development

git clone git@github.com:smridge/swagcov.git

Add this line to your application's Gemfile:

 # Use the relative path from your application, to the swagcov folder
gem "swagcov", path: "../swagcov"

bundle

Run Tests

bundle exec rspec spec --exclude-pattern spec/sandbox_**/**/*_spec.rb

Test via Sandbox Application

• Go to any sandbox application within the spec directory
  • For example, cd spec/sandbox_5_2/
• Install the ruby version specified in .ruby-version file
• Install gems: bundle install
• Run tests: bundle exec rspec spec
• Run bundle exec rake swagcov
  • This will run against any changes made to your branch.

Publish (internal)

Note: Publishing a new version of this gem is only meant for maintainers.

• Ensure you have access to publish on rubygems.
• Update CHANGELOG.
• Update VERSION.
• Run bundle update for each sandbox application to reflect new swagcov version in each Gemfile.lock
• Open a Pull Request to ensure all specs pass, then merge to main.
• Checkout the latest main on your machine.
• Run: rake release
  • This command builds the gem, creates a tag and publishes to rubygems, see bundler docs.

TODO

• Create Rails 7 / Ruby 3.1 Sandbox
• Add autogeneration of ignore paths
• Add CONTRIBUTING.md
• Add GitHub Action for linting

Credit

To @lonelyelk for initial development!

Contributors