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:

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

  

• With ignore and only endpoint configurations:

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

  

Development

git clone [email protected]: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

Credit

To @lonelyelk for initial development!

Contributors