swagcov 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c84f31d41e49c7d90290cbdc863d512896100660cf777b66fc2a41837dafadf5
+  data.tar.gz: 87af9e2410c54d994f4c6d2832b7a905216aba3a4d25a27691ec49f78c8f5715
+SHA512:
+  metadata.gz: 28db77ab060836b1b98a4e38de339b96f613de5d954f67050840f722a0d6b484c2d12da003479999ebcee42d506963826a776a28faaa85bb9d437b4a44e178cb
+  data.tar.gz: 382179ddd4f08e04823f0c9bf2f2f8925ba1929bc12d6baadb0882de172684a8361d95fddb55b66ab5669e76cc3d6062bac9cf3f5c1a0d4149273fa27d35b6ab

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright 2021 Sarah Ridge
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,81 @@
+# Swagcov
+See coverage report for openapi docs for Rails Routes.
+
+## 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/v1/swagger.yaml
+  ```
+
+- Add `only` routes (**optional**) :
+  ```yml
+  routes:
+    paths:
+      only:
+        - ^/v1
+  ```
+
+- Add `ignore` routes (**optional**) :
+  ```yml
+  routes:
+    paths:
+      ignore:
+        - /v1/foobar/:token
+        - /sidekiq
+  ```
+
+- Example `.swagcov.yml` Config File:
+  ```yml
+  docs:
+    paths:
+      - swagger/v1/swagger.yaml
+
+  routes:
+    paths:
+      only:
+        - ^/v1
+      ignore:
+        - /v1/foobar/:token
+        - /sidekiq
+  ```
+
+Execute:
+```shell
+bundle exec rake swagcov
+```
+
+## Development
+```shell
+git clone git@github.com: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
+```
+
+## TODO
+- Add specs
+- Test against different rails versions
+- Add autogeneration of ignore paths
+
+## Credit
+To [@lonelyelk](https://github.com/lonelyelk) for initial development!

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"

data/lib/swagcov.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "swagcov/version"
+
+if defined?(Rails)
+  require "swagcov/railtie"
+  require "swagcov/coverage"
+end
+
+module Swagcov
+end

data/lib/swagcov/coverage.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Swagcov
+  class Coverage
+    def initialize
+      @total = 0
+      @covered = 0
+      @ignored = 0
+      @routes_not_covered = []
+      @routes_covered = []
+      @routes_ignored = []
+    end
+
+    def report
+      Rails.application.routes.routes.each do |route|
+        path = route.path.spec.to_s.sub(/\(\.:format\)$/, "")
+
+        if ignore_path?(path)
+          @ignored += 1
+          @routes_ignored << { verb: route.verb, path: path, status: "ignored" }
+          next
+        end
+
+        next if 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))
+          @covered += 1
+          @routes_covered << { verb: route.verb, path: path, status: doc["responses"].keys.map(&:to_s).sort.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
+
+      (@total - @covered).zero?
+    end
+
+    def dotfile
+      @dotfile ||= YAML.load_file(Rails.root.join(".swagcov.yml"))
+    end
+
+    def docs_paths
+      @docs_paths ||= Dir.glob(dotfile["docs"]["paths"]).reduce({}) do |acc, docspath|
+        acc.merge(YAML.load_file(docspath)["paths"])
+      end
+    end
+
+    private
+
+    def ignore_path? path
+      ignored_regex&.match?(path)
+    end
+
+    def ignored_regex
+      @ignored_regex ||= path_config_regex(dotfile.dig("routes", "paths", "ignore"))
+    end
+
+    def only_path_mismatch? path
+      only_regex && !only_regex.match?(path)
+    end
+
+    def only_regex
+      @only_regex ||= path_config_regex(dotfile.dig("routes", "paths", "only"))
+    end
+
+    def path_config_regex path_config
+      return unless path_config
+
+      config = path_config.map { |path| path.first == "^" ? path : "#{path}$" }
+
+      /#{config.join('|')}/
+    end
+
+    def routes_output routes, status_color
+      routes.each do |route|
+        $stdout.puts(
+          format(
+            "%<verb>10s    %<path>-90s    %<status>s",
+            { verb: route[:verb], path: route[:path], status: route[:status].send(status_color) }
+          )
+        )
+      end
+    end
+
+    def final_output
+      $stdout.puts
+      $stdout.puts(
+        format(
+          "OpenAPI documentation coverage %<percentage>.2f%% (%<covered>d/%<total>d)",
+          { percentage: 100.0 * @covered / @total, covered: @covered, total: @total }
+        )
+      )
+
+      $stdout.puts(
+        format(
+          "%<total>s endpoints ignored",
+          { total: @ignored.to_s.yellow }
+        )
+      )
+
+      $stdout.puts(
+        format(
+          "%<total>s endpoints checked",
+          { total: @total.to_s.blue }
+        )
+      )
+
+      $stdout.puts(
+        format(
+          "%<covered>s endpoints covered",
+          { covered: @covered.to_s.green }
+        )
+      )
+
+      $stdout.puts(
+        format(
+          "%<missing>s endpoints missing documentation",
+          { missing: (@total - @covered).to_s.red }
+        )
+      )
+    end
+  end
+end

data/lib/swagcov/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Swagcov
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      path = File.expand_path("..", __dir__)
+
+      Dir.glob("#{path}/tasks/**/*.rake").each { |f| load f }
+    end
+  end
+end

data/lib/swagcov/version.rb

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

data/lib/tasks/swagcove.rake

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+desc "check documentation coverage for endpoints"
+task swagcov: :environment do
+  Swagcov::Coverage.new.report
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: swagcov
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sarah Ridge
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-02-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: 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'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  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: rubocop-performance
+  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
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/swagcov.rb
+- lib/swagcov/coverage.rb
+- lib/swagcov/railtie.rb
+- lib/swagcov/version.rb
+- lib/tasks/swagcove.rake
+homepage: https://github.com/smridge/swagcov
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  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
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: Open API docs coverage for Rails Routes
+test_files: []