swagcov 0.2.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83f05163f3408b08db9f9810e5eb82a4285877d9e7b7af60a83e44386eab5c04
-  data.tar.gz: 76b1bf03e51bc42e516f5b77536d1ae38685dd642823094a0ac8e67fa8c67ac3
+  metadata.gz: 8aec9444a5e8dfd1d4b23fc61c710d4ccc28d5c7985df0fbef5e8c02e16e7519
+  data.tar.gz: a19a3c8f73ad9efb814ff7469b6306bacb52d296893130b7fb42740d1d7e7db4
 SHA512:
-  metadata.gz: 82610986597a8a832173354fb452a4d63c7c0a22a342ec10fd2ac6bcb3eef845d306c6d37225ac837b22febcb12a0ba093167b71d3acc94aaabb8394789b77a7
-  data.tar.gz: a1cdf7691af9fce07dfc50711a748bcbfe903ef0f5f5b94e3d1b3d7fd605ac125de92db23121a8ccdb8622494bfba431f7f3710e55f6392a20160e5c2bfd4e4f
+  metadata.gz: cc64199a92c0322fe3c42bbaa882d103a9a8f18e1c3dbe02ddb5b56bb21d13eae763536fbcdb2f84aa8a045fb6d92726f1a953eaa27595118cbe6a7324dd5c2a
+  data.tar.gz: 9713fa38210e7f6273e2f9004a7dc791994ebd80e50e0852381de005f67b1c238ce995060c3643b2b1db7520d46687defa554067e3ff2a75ae71ec70a809f496

data/README.md

@@ -1,5 +1,14 @@
 # Swagcov
-See coverage report for openapi docs for Rails Routes.
+[![Gem Version](https://img.shields.io/gem/v/swagcov)](https://rubygems.org/gems/swagcov)
+![Gem Downloads](https://img.shields.io/gem/dt/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)
+
+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:
@@ -17,7 +26,7 @@ Create a `.swagcov.yml` in root of your Rails application.
   ```yml
   docs:
     paths:
-      - swagger/v1/swagger.yaml
+      - swagger.yaml
   ```
 
 - Add `only` routes (**optional**) :
@@ -34,14 +43,13 @@ Create a `.swagcov.yml` in root of your Rails application.
     paths:
       ignore:
         - /v1/foobar/:token
-        - /sidekiq
   ```
 
-- Example `.swagcov.yml` Config File:
+- Full Example `.swagcov.yml` Config File:
   ```yml
   docs:
     paths:
-      - swagger/v1/swagger.yaml
+      - swagger.yaml
 
   routes:
     paths:
@@ -49,7 +57,6 @@ Create a `.swagcov.yml` in root of your Rails application.
         - ^/v1
       ignore:
         - /v1/foobar/:token
-        - /sidekiq
   ```
 
 Execute:
@@ -57,6 +64,44 @@ 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):
+  ```yml
+  docs:
+    paths:
+      - swagger.yaml
+  ```
+  <img src="https://raw.githubusercontent.com/smridge/swagcov/main/images/all-endpoints.png">
+
+
+- With `only` endpoint configuration:
+  ```yml
+  docs:
+    paths:
+      - swagger.yaml
+
+  routes:
+    paths:
+      only:
+        - ^/v2
+  ```
+  <img src="https://raw.githubusercontent.com/smridge/swagcov/main/images/only-endpoints.png">
+
+- With `ignore` and `only` endpoint configurations:
+  ```yml
+  docs:
+    paths:
+      - swagger.yaml
+
+  routes:
+    paths:
+      only:
+        - ^/v2
+      ignore:
+        - /v2/users
+  ```
+  <img src="https://raw.githubusercontent.com/smridge/swagcov/main/images/ignore-and-only-endpoints.png">
+
 ## Development
 ```shell
 git clone git@github.com:smridge/swagcov.git
@@ -72,22 +117,41 @@ 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](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).
-- Commit changes to `main` branch locally.
+- 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
-- Add specs
-- Test against different rails versions
-- Create Sandbox Apps for Rails 5 & 6
+- Create Rails 7 / Ruby 3.1 Sandbox
 - Add autogeneration of ignore paths
 - Add `CONTRIBUTING.md`
-- Add GitHub Actions for specs/linting
+- Add GitHub Action for linting
 
 ## Credit
 To [@lonelyelk](https://github.com/lonelyelk) for initial development!
+
+## Contributors
+<a href="https://github.com/smridge/swagcov/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=smridge/swagcov" />
+</a>

data/lib/swagcov/coverage.rb

@@ -2,31 +2,41 @@
 
 module Swagcov
   class Coverage
-    def initialize
+    attr_reader :total, :covered, :ignored, :routes_not_covered, :routes_covered, :routes_ignored
+
+    def initialize dotfile: Swagcov::Dotfile.new, routes: ::Rails.application.routes.routes
       @total = 0
       @covered = 0
       @ignored = 0
       @routes_not_covered = []
       @routes_covered = []
       @routes_ignored = []
-      @dotfile = Swagcov::Dotfile.new
+      @dotfile = dotfile
+      @routes = routes
     end
 
     def report
-      Rails.application.routes.routes.each do |route|
-        # 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"]
-        next if route.internal
+      collect_coverage
+      routes_output(@routes_covered, "green")
+      routes_output(@routes_ignored, "yellow")
+      routes_output(@routes_not_covered, "red")
 
-        # Skips routes like "/sidekiq"
-        next unless route.verb.present?
+      final_output
 
-        path = route.path.spec.to_s.sub(/\(\.:format\)$/, "")
+      @total - @covered
+    end
 
-        # 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
-        next if path.include?("/active_storage/") || path.include?("/action_mailbox/")
+    private
+
+    attr_reader :dotfile
+
+    def collect_coverage
+      openapi_files = ::Swagcov::OpenapiFiles.new(filepaths: dotfile.doc_paths)
+
+      @routes.each do |route|
+        path = route.path.spec.to_s.chomp("(.:format)")
+
+        next if third_party_route?(route, path)
 
         if dotfile.ignore_path?(path)
           @ignored += 1
@@ -37,41 +47,35 @@ module Swagcov
         next if dotfile.only_path_mismatch?(path)
 
         @total += 1
-        regex = Regexp.new("#{path.gsub(%r{:[^/]+}, '\\{[^/]+\\}')}(\\.[^/]+)?$")
-        matching_keys = docs_paths.keys.select { |k| regex.match?(k) }
 
-        if (doc = docs_paths.dig(matching_keys.first, route.verb.downcase))
+        if (response_keys = openapi_files.find_response_keys(path: path, route_verb: route.verb))
           @covered += 1
-          @routes_covered << { verb: route.verb, path: path, status: doc["responses"].keys.map(&:to_s).sort.join("  ") }
+          @routes_covered << { verb: route.verb, path: path, status: response_keys.join("  ") }
         else
           @routes_not_covered << { verb: route.verb, path: path, status: "none" }
         end
       end
-
-      routes_output(@routes_covered, "green")
-      routes_output(@routes_ignored, "yellow")
-      routes_output(@routes_not_covered, "red")
-
-      final_output
-
-      exit @total - @covered
     end
 
-    def docs_paths
-      @docs_paths ||= Dir.glob(dotfile.doc_paths).reduce({}) do |acc, docspath|
-        acc.merge(YAML.load_file(docspath)["paths"])
-      end
-    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"]
+      route.internal ||
 
-    private
+        # Skips routes like "/sidekiq"
+        route.verb.blank? ||
 
-    attr_reader :dotfile
+        # 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/")
+    end
 
     def routes_output routes, status_color
       routes.each do |route|
         $stdout.puts(
           format(
-            "%<verb>10s    %<path>-90s    %<status>s",
+            "%<verb>10s %<path>-90s %<status>s",
             { verb: route[:verb], path: route[:path], status: route[:status].send(status_color) }
           )
         )

data/lib/swagcov/dotfile.rb

@@ -5,12 +5,12 @@ module Swagcov
   end
 
   class Dotfile
-    def initialize
-      pathname = Rails.root.join(".swagcov.yml")
-      raise BadConfigurationError, "Missing .swagcov.yml" unless pathname.exist?
+    DEFAULT_CONFIG_FILE_NAME = ".swagcov.yml"
 
-      @dotfile = YAML.load_file(pathname)
-      raise BadConfigurationError, "Invalid .swagcov.yml" unless valid?
+    def initialize pathname: ::Rails.root.join(DEFAULT_CONFIG_FILE_NAME)
+      @dotfile = load_yaml(pathname)
+
+      raise BadConfigurationError, "Invalid config file (#{DEFAULT_CONFIG_FILE_NAME})" unless valid?
     end
 
     def ignore_path? path
@@ -29,6 +29,14 @@ module Swagcov
 
     attr_reader :dotfile
 
+    def load_yaml pathname
+      raise BadConfigurationError, "Missing config file (#{DEFAULT_CONFIG_FILE_NAME})" unless pathname.exist?
+
+      YAML.load_file(pathname)
+    rescue Psych::SyntaxError
+      raise BadConfigurationError, "Malinformed config file (#{DEFAULT_CONFIG_FILE_NAME})"
+    end
+
     def ignored_regex
       @ignored_regex ||= path_config_regex(dotfile.dig("routes", "paths", "ignore"))
     end

data/lib/swagcov/openapi_files.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Swagcov
+  class OpenapiFiles
+    def initialize filepaths:
+      @filepaths = filepaths
+      @openapi_paths = load_yamls
+    end
+
+    def find_response_keys path:, route_verb:
+      # replace :id with {id}
+      regex = Regexp.new("^#{path.gsub(%r{:[^/]+}, '\\{[^/]+\\}')}?$")
+
+      matching_paths_key = @openapi_paths.keys.grep(regex).first
+      matching_request_method_key = @openapi_paths.dig(matching_paths_key, route_verb.downcase)
+
+      matching_request_method_key["responses"].keys.map(&:to_s).sort if matching_request_method_key
+    end
+
+    private
+
+    def load_yamls
+      Dir.glob(@filepaths).reduce({}) do |hash, filepath|
+        hash.merge(load_yaml(filepath))
+      end
+    end
+
+    def load_yaml filepath
+      YAML.load_file(filepath)["paths"]
+    rescue Psych::SyntaxError
+      raise BadConfigurationError, "Malinformed openapi file (#{filepath})"
+    end
+  end
+end

data/lib/swagcov/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Swagcov
-  VERSION = "0.2.4"
+  VERSION = "0.4.0"
 end

data/lib/swagcov.rb

@@ -6,6 +6,7 @@ if defined?(Rails)
   require "swagcov/railtie"
   require "swagcov/dotfile"
   require "swagcov/coverage"
+  require "swagcov/openapi_files"
 end
 
 require "swagcov/core_ext/string"

data/lib/tasks/swagcove.rake

@@ -2,5 +2,5 @@
 
 desc "check documentation coverage for endpoints"
 task swagcov: :environment do
-  Swagcov::Coverage.new.report
+  exit Swagcov::Coverage.new.report
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: swagcov
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.4.0
 platform: ruby
 authors:
 - Sarah Ridge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-30 00:00:00.000000000 Z
+date: 2022-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '5'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description:
 email:
 - sarahmarie@hey.com
@@ -80,6 +108,7 @@ files:
 - lib/swagcov/core_ext/string.rb
 - lib/swagcov/coverage.rb
 - lib/swagcov/dotfile.rb
+- lib/swagcov/openapi_files.rb
 - lib/swagcov/railtie.rb
 - lib/swagcov/version.rb
 - lib/tasks/swagcove.rake
@@ -91,6 +120,7 @@ metadata:
   homepage_uri: https://github.com/smridge/swagcov
   source_code_uri: https://github.com/smridge/swagcov
   changelog_uri: https://github.com/smridge/swagcov/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -106,7 +136,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.33
 signing_key:
 specification_version: 4
 summary: Open API docs coverage for Rails Routes