Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/smridge/swagcov
OpenAPI documentation coverage check for Rails Routes.
https://github.com/smridge/swagcov
openapi rspec rswag ruby
Last synced: 3 months ago
JSON representation
OpenAPI documentation coverage check for Rails Routes.
- Host: GitHub
- URL: https://github.com/smridge/swagcov
- Owner: smridge
- License: mit
- Created: 2021-02-23T04:36:40.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2023-01-11T03:57:51.000Z (about 2 years ago)
- Last Synced: 2024-04-25T09:43:54.980Z (9 months ago)
- Topics: openapi, rspec, rswag, ruby
- Language: Ruby
- Homepage:
- Size: 2.21 MB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Swagcov
[](https://rubygems.org/gems/swagcov)
[](https://github.com/rubocop-hq/rubocop)
[](https://github.com/smridge/swagcov/blob/main/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:
```ruby
gem "swagcov"
```
Execute:
```shell
bundle
```
Create a `.swagcov.yml` in root of your Rails application.
- Add the paths of your `openapi` yml files (**required**):
```yml
docs:
paths:
- swagger.yaml
```
- Add `only` routes (**optional**) :
```yml
routes:
paths:
only:
- ^/v1
```
- Add `ignore` routes (**optional**) :
```yml
routes:
paths:
ignore:
- /v1/foobar/:token
```
- Full Example `.swagcov.yml` Config File:
```yml
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):
```yml
docs:
paths:
- swagger.yaml
```
- With `only` endpoint configuration:
```yml
docs:
paths:
- swagger.yaml
routes:
paths:
only:
- ^/v2
```
- With `ignore` and `only` endpoint configurations:
```yml
docs:
paths:
- swagger.yaml
routes:
paths:
only:
- ^/v2
ignore:
- /v2/users
```
## Development
```shell
git clone [email protected]:smridge/swagcov.git
```
Add this line to your application's Gemfile:
```ruby
# Use the relative path from your application, to the swagcov folder
gem "swagcov", path: "../swagcov"
```
```shell
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](https://rubygems.org/gems/swagcov).
- Update [CHANGELOG](https://github.com/smridge/swagcov/blob/main/CHANGELOG.md).
- Update [`VERSION`](https://github.com/smridge/swagcov/blob/main/lib/swagcov/version.rb).
- 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](https://bundler.io/guides/creating_gem.html#releasing-the-gem).
## TODO
- Create Rails 7 / Ruby 3.1 Sandbox
- Add autogeneration of ignore paths
- Add `CONTRIBUTING.md`
## Credit
To [@lonelyelk](https://github.com/lonelyelk) for initial development!
## Contributors
