Project

swagcov

0.0
No release in over a year
Open API docs coverage for Rails Routes
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

Runtime

>= 5
 Project Readme

Swagcov

Gem Version Gem Downloads Ruby Style Guide GitHub License

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

Credit

To @lonelyelk for initial development!

Contributors