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:

“by gem “swagcov”

“

Execute:

“ell bundle

“

Create a .swagcov.yml in root of your Rails application. - Add the paths of your openapi yml files (required): “l docs: paths: - swagger.yaml “

• Add only routes (optional) :

  “l routes: paths: only: - ^/v1

  “

• Add ignore routes (optional) :

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

  “

• Full Example .swagcov.yml Config File:

  “l docs: paths: - swagger.yaml

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

  “

Execute:

“ell 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):

  “l docs: paths: - swagger.yaml

  “img src=“https://raw.githubusercontent.com/smridge/swagcov/main/images/all-endpoints.png”>

• With only endpoint configuration:

  “l 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:

  “l docs: paths: - swagger.yaml

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

  “img src=“https://raw.githubusercontent.com/smridge/swagcov/main/images/ignore-and-only-endpoints.png”>

Development

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

“

Add this line to your application’s Gemfile:

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

“

“ell bundle

“

Run Tests

“undle 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