swagcov 0.11.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3102d52e8495c610e219ad58a32c75a3575cbd0460f1fddefdb5d427ff4e9f5e
-  data.tar.gz: 7f64fbc51d03dec663fea9dec838615f12d287d7f6a83f813e1f5411e6f11f8a
+  metadata.gz: 25a95a511f8848ad55e88aba10b52e91b98b4a763f3c459e8d7167115846b9b0
+  data.tar.gz: 8ef18bdf421bf494882c799d76146804af7dc5b92fc8333c26c80c087231cec2
 SHA512:
-  metadata.gz: 233f4668cb3e3ffa15b8354543c17f6879d50e5d077cf9aa55ea3aeb3c7d0f0f42bd7de4a7d5383987268377734ba90ac737f7bd3e02bb17a0d337ab3f348a96
-  data.tar.gz: b420010ec3553036c2ea18ceb3d14d1f080b3af9ced0daa432a3d7a47d70a0d9beaee4baacc1dc0747df4701d7b447088177d27d8f415d7486480d89c73dffe0
+  metadata.gz: 37f8c1fb82a83466f03c3c12026d23f749a8fb6fc84a643030d7e11c9ac44299dc628642a2f2742ca7decd54103aaf2e3567c775378ad940028dac192b329558
+  data.tar.gz: 84e0bc9fb5808202680ab6f7ac740f61c8b16edacf7b4b362483ccd727df41e80ac17bf5f3b0f1eb6be8811d7cb027b2c84c2bea7c76686feced9446416e5826

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 ## main (unreleased)
 -
 
+## 1.1.0 (2025-08-07)
+### Enhancement
+- Exclude `new` and `edit` controller action routes that are non api routes by rails defaults/convention ([#155](https://github.com/smridge/swagcov/pull/155))
+  - For example the below routes are now automatically skipped since these are _generally_ `html` formats.
+    ```
+           Prefix Verb   URI Pattern                     Controller#Action
+      new_article GET    /articles/new(.:format)         articles#new
+     edit_article GET    /articles/:id/edit(.:format)    articles#edit
+    ```
+- Exclude `turbo-rails` related routes (part of rails frameworks that are not considered part of your OpenAPI documentation) ([#156](https://github.com/smridge/swagcov/pull/156))
+
+## 1.0.0 (2025-05-20)
+### Refactor
+- Default Environment Variable approach ([#143](https://github.com/smridge/swagcov/pull/143))
+- `swagcov` is considered tested and stable for a version 1.0.0 release, see [README](/README.md) for documentation
+
 ## 0.11.0 (2025-05-13)
 ### Enhancement
 - Add swagcov `version` option ([#134](https://github.com/smridge/swagcov/pull/134))
@@ -113,7 +129,7 @@
 ### Code Coverage
   - Added official support for ruby 3.3 and 3.4 and rails 7.1, 7.2, 8.0. See [tests.yml](/.github/workflows/tests.yml) for detail
 
-## 0.4.0 (2022-08-11)
+## 0.4.0 (2022-08-12)
   - Improve OpenAPI file processing ([#26](https://github.com/smridge/swagcov/pull/26))
 
 ## 0.3.0 (2022-02-21)

data/README.md

@@ -1,6 +1,7 @@
 # Swagcov
-[![Gem Version](https://img.shields.io/gem/v/swagcov)](https://rubygems.org/gems/swagcov)
-![Gem Downloads](https://img.shields.io/gem/dt/swagcov)
+[![Gem Version](https://img.shields.io/gem/v/swagcov?logo=rubygems)](https://rubygems.org/gems/swagcov)
+[![GitHub Top Language](https://img.shields.io/github/languages/top/smridge/swagcov)](https://rubygems.org/gems/swagcov)
+[![Gem Downloads](https://img.shields.io/gem/dt/swagcov)](https://rubygems.org/gems/swagcov)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop-hq/rubocop)
 [![GitHub License](https://img.shields.io/github/license/smridge/swagcov.svg)](https://github.com/smridge/swagcov/blob/main/LICENSE)
 
@@ -47,6 +48,21 @@ The approaches below are listed in the following order:
 - `rake swagcov -- --help`
 - `Swagcov::Runner.new(args: ["--help"]).run`
 
+### Environment Variables
+The following default environment variables are automatically set (and can optionally be changed to your needs)
+| Key                | Value               |
+| :---               | :---                |
+| `SWAGCOV_DOTFILE`  | `.swagcov.yml`      |
+| `SWAGCOV_TODOFILE` | `.swagcov_todo.yml` |
+
+For example `SWAGCOV_DOTFILE=".openapi_coverage_config.yml" bundle exec swagcov`
+
+### Exit Codes
+`swagcov` exits with the following status codes:
+- `0` - (`success`) if no missing documentation coverage is detected
+- `1` - (`offenses`) if missing documentation coverage is detected
+- `2` - (`error`) if abnormal termination due to invalid configuration, cli options, or an internal error
+
 ## Ruby and Rails Version Support
 Versioning support from a test coverage perspective, see [tests.yml](/.github/workflows/tests.yml) for detail
 | `ruby -v` | `rails 4.2` | `rails 5.0` | `rails 5.1` | `rails 5.2` | `rails 6.0` | `rails 6.1` | `rails 7.0` | `rails 7.1` | `rails 7.2` | `rails 8.0` |
@@ -62,68 +78,87 @@ Versioning support from a test coverage perspective, see [tests.yml](/.github/wo
 | `3.5`     | ❌          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          | ✅          |
 
 ## 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. Alternatively, run:
-```shell
-bundle exec rake swagcov:install
-```
-
-- Add the paths of your OpenAPI `.yml` and/or `.json` files (**required**):
-  ```yml
-  docs:
-    paths:
-      - swagger.yaml
-      - swagger.json
+- Add this line to your application's Gemfile:
+  ```ruby
+  gem "swagcov"
   ```
 
-- Add `only` routes (**optional**) :
-  ```yml
-  routes:
-    paths:
-      only:
-        - ^/v1
-  ```
+- Execute `bundle install` to install the gem
 
-- Add `ignore` routes (**optional**) :
-  ```yml
-  routes:
-    paths:
-      ignore:
-        - /v1/foobar/:token
+- Generate the required `.swagcov.yml` configuration file in the root of your Rails application by executing one of the following commands:
+  ```
+  bundle exec swagcov --init
+  bundle exec rake swagcov -- --init
   ```
 
-- Full Example `.swagcov.yml` Config File:
-  ```yml
+  You should now see the following file to configure to your needs:
+  ```yaml
+  ## Required field:
+  # List your OpenAPI documentation file(s) (accepts json or yaml)
   docs:
     paths:
       - swagger.yaml
+      - swagger.json
 
-  routes:
-    paths:
-      only:
-        - ^/v1
-      ignore:
-        - /v1/foobar/:token
-        - /v1/foobar:
-          - GET
+  ## Optional fields:
+  # routes:
+  #   paths:
+  #     only:
+  #       - ^/v2 # only track v2 endpoints
+  #     ignore:
+  #       - /v2/users # do not track certain endpoints
+  #       - /v2/users/:id: # ignore only certain actions (verbs)
+  #         - GET
   ```
 
-Execute:
-```shell
-bundle exec rake swagcov
-```
+- Execute one of the following commands:
+  ```
+  bundle exec swagcov
+  bundle exec rake swagcov
+  ```
+
+  Example Output:
+  ```
+       GET /articles         200
+     PATCH /articles/:id     200
+    DELETE /articles/:id     204
+       GET /users            200
+      POST /users            201
+       GET /users/:id        200
+       PUT /users/:id        200
+    DELETE /users/:id        204
+       GET /v1/articles      200
+      POST /v1/articles      201
+       GET /v1/articles/:id  200
+     PATCH /v1/articles/:id  200
+       PUT /v1/articles/:id  200
+    DELETE /v1/articles/:id  204
+       GET /v2/articles      200
+      POST /v2/articles      201
+     PATCH /v2/articles/:id  200
+    DELETE /v2/articles/:id  204
+       GET /v2/articles/:id  ignored
+       PUT /v2/articles/:id  ignored
+      POST /articles         none
+       GET /articles/:id     none
+       PUT /articles/:id     none
+     PATCH /users/:id        none
+
+  OpenAPI documentation coverage 81.82% (18/22)
+  2 ignored endpoints
+  22 total endpoints
+  18 covered endpoints
+  4 uncovered endpoints
+  ```
+
+- Optionally generate a `.swagcov_todo.yml` config file acting as a TODO list
+  ```
+  bundle exec swagcov --todo
+  bundle exec rake swagcov -- --todo
+  ```
 
 ## Examples
-Configurations and output from running `bundle exec rake swagcov` from the root of your Rails Application
+Configurations and output from running `swagcov` / `rake swagcov` from the root of your Rails Application
 - All Routes (minimal configuration):
   ```yml
   docs:

data/lib/swagcov/command/generate_dotfile.rb

@@ -5,7 +5,7 @@ module Swagcov
     class GenerateDotfile
       attr_reader :dotfile
 
-      def initialize basename: ::Swagcov::Dotfile::DEFAULT_CONFIG_FILE_NAME
+      def initialize basename: ::Swagcov::DOTFILE
         @dotfile = ::Swagcov.project_root.join(basename)
       end
 

data/lib/swagcov/command/generate_todo_file.rb

@@ -3,7 +3,7 @@
 module Swagcov
   module Command
     class GenerateTodoFile
-      def initialize basename: ::Swagcov::Dotfile::TODO_CONFIG_FILE_NAME,
+      def initialize basename: ::Swagcov::TODOFILE,
                      data: ::Swagcov::Coverage.new(dotfile: ::Swagcov::Dotfile.new(skip_todo: true)).collect[:uncovered]
         @dotfile = ::Swagcov.project_root.join(basename)
         @data = data

data/lib/swagcov/coverage.rb

@@ -23,7 +23,7 @@ module Swagcov
         path = route_path(route)
         verb = route_verb(route)
 
-        next if third_party_route?(route, path)
+        next if default_skipped_route?(route, path)
 
         if dotfile.ignore_path?(path, verb: verb)
           update_data(:ignored, verb, path, "ignored")
@@ -56,6 +56,10 @@ module Swagcov
       rails_version > "5" ? route.verb : route.verb.inspect.gsub(%r{[$^/]}, "")
     end
 
+    def default_skipped_route? route, path
+      third_party_route?(route, path) || non_api_route?(route, path)
+    end
+
     def third_party_route? route, path
       # https://github.com/rails/rails/blob/48f3c3e201b57a4832314b2c957a3b303e89bfea/actionpack/lib/action_dispatch/routing/inspector.rb#L105-L107
       # Skips route paths like ["/rails/info/properties", "/rails/info", "/rails/mailers"]
@@ -64,10 +68,10 @@ module Swagcov
         # Skips routes like "/sidekiq"
         route.verb.blank? ||
 
-        # Exclude routes that are part of the rails gem that you would not write documentation for
-        # https://github.com/rails/rails/tree/main/activestorage/app/controllers/active_storage
-        # https://github.com/rails/rails/tree/main/actionmailbox/app/controllers/action_mailbox
-        path.include?("/active_storage/") || path.include?("/action_mailbox/")
+        # Exclude routes that are part of the rails frameworks that you would not write documentation for
+        path.include?("/active_storage/") ||
+        path.include?("/action_mailbox/") ||
+        turbo_rails_route?(route, path)
     end
 
     def internal_rails_route? route
@@ -78,6 +82,16 @@ module Swagcov
       end
     end
 
+    def turbo_rails_route? route, path
+      # TODO: add route.source_location.include?("turbo-rails") - working on local machine but not in test env
+      path.include?("_historical_location") && route.name.include?("turbo_")
+    end
+
+    def non_api_route? route, path
+      # By default/convention these are non api routes generated by rails
+      %w[new edit].include?(route.defaults[:action]) && (path.include?("/new") || path.include?("/edit"))
+    end
+
     def update_data key, verb, path, status
       @data[:"#{key}_count"] += 1
       @data[key] << { verb: verb, path: path, status: status }

data/lib/swagcov/dotfile.rb

@@ -2,13 +2,10 @@
 
 module Swagcov
   class Dotfile
-    DEFAULT_CONFIG_FILE_NAME = ::ENV.fetch("SWAGCOV_DOTFILE", ".swagcov.yml")
-    TODO_CONFIG_FILE_NAME = ::ENV.fetch("SWAGCOV_TODOFILE", ".swagcov_todo.yml")
-
-    def initialize basename: DEFAULT_CONFIG_FILE_NAME, todo_basename: TODO_CONFIG_FILE_NAME, skip_todo: false
+    def initialize basename: ::Swagcov::DOTFILE, todo_basename: ::Swagcov::TODOFILE, skip_todo: false
       @dotfile = load_yaml(basename, required: true)
 
-      raise ::Swagcov::Errors::BadConfiguration, "Invalid config file (#{DEFAULT_CONFIG_FILE_NAME})" unless valid?
+      raise ::Swagcov::Errors::BadConfiguration, "Invalid config file (#{::Swagcov::DOTFILE})" unless valid?
 
       @todo_file = load_yaml(todo_basename) unless skip_todo
       @ignored_regex = path_config_regex(ignored_config)

data/lib/swagcov/version.rb

@@ -2,6 +2,6 @@
 
 module Swagcov
   module Version
-    STRING = "0.11.0"
+    STRING = "1.1.0"
   end
 end

data/lib/swagcov.rb

@@ -24,6 +24,9 @@ module Swagcov
   STATUS_OFFENSES    = 1
   STATUS_ERROR       = 2
 
+  DOTFILE = ENV["SWAGCOV_DOTFILE"] ||= ".swagcov.yml"
+  TODOFILE = ENV["SWAGCOV_TODOFILE"] ||= ".swagcov_todo.yml"
+
   def project_root
     ::Rails.root || ::Pathname.new(::FileUtils.pwd)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swagcov
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Sarah Ridge
@@ -73,7 +73,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 3.7.0.dev
 specification_version: 4
 summary: OpenAPI documentation coverage report for Rails Route endpoints
 test_files: []