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
andonly
endpoint configurations: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/
- For example,
- 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 eachGemfile.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!