swagcov 0.11.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3102d52e8495c610e219ad58a32c75a3575cbd0460f1fddefdb5d427ff4e9f5e
-  data.tar.gz: 7f64fbc51d03dec663fea9dec838615f12d287d7f6a83f813e1f5411e6f11f8a
+  metadata.gz: 142f669b882f17b5a640aa9cd72b0cc12019cda4e4bc48d9fea5d432fcfff505
+  data.tar.gz: 5eac1740f216095d93ec1d0f69553eab305aa60ac8e8fb3935a9d75446db05ea
 SHA512:
-  metadata.gz: 233f4668cb3e3ffa15b8354543c17f6879d50e5d077cf9aa55ea3aeb3c7d0f0f42bd7de4a7d5383987268377734ba90ac737f7bd3e02bb17a0d337ab3f348a96
-  data.tar.gz: b420010ec3553036c2ea18ceb3d14d1f080b3af9ced0daa432a3d7a47d70a0d9beaee4baacc1dc0747df4701d7b447088177d27d8f415d7486480d89c73dffe0
+  metadata.gz: 283c6d98acb19f7184ba06ef95a184fcb2844062647699a934ffd5ecb1f4f1c34f47df7cd5ede1aae39a4277f84c3237aed655e4268094921b48ac34ef0f1b73
+  data.tar.gz: 6107ded5f46b2472d38dc4a454ff01bb8da7dcbddc1668b22858031e38a8c3097781b32c794dfbd064a9e13e19d426482d06c1c9935059725069e94255b76cdd

data/CHANGELOG.md

@@ -2,6 +2,11 @@
 ## main (unreleased)
 -
 
+## 1.0.0 (2025-05-19)
+### 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))

data/README.md

@@ -47,6 +47,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 +77,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/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.0.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.0.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.6.9
 specification_version: 4
 summary: OpenAPI documentation coverage report for Rails Route endpoints
 test_files: []