RubyGems - reqcord - Versions diffs - 0.1.4 → 0.3.0 - Mend

reqcord 0.1.4 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +42 -0
data/README.md +115 -713
data/docs/architecture.md +134 -0
data/docs/capture.md +169 -0
data/docs/configuration.md +32 -3
data/docs/exporters.md +182 -0
data/docs/getting-started.md +186 -0
data/docs/route-coverage.md +91 -0
data/docs/troubleshooting.md +113 -0
data/docs/web.md +66 -0
data/examples/reqcord.yml +3 -1
data/lib/reqcord/capture/integration_patch.rb +9 -2
data/lib/reqcord/check.rb +73 -0
data/lib/reqcord/configuration.rb +10 -1
data/lib/reqcord/dataset.rb +0 -1
data/lib/reqcord/exporters/markdown.rb +5 -2
data/lib/reqcord/exporters/openapi.rb +295 -0
data/lib/reqcord/exporters/postman.rb +11 -1
data/lib/reqcord/file_value.rb +62 -0
data/lib/reqcord/generator.rb +17 -3
data/lib/reqcord/renderers/curl.rb +22 -1
data/lib/reqcord/renderers/payload.rb +25 -7
data/lib/reqcord/route_collector.rb +10 -1
data/lib/reqcord/schema.rb +11 -1
data/lib/reqcord/version.rb +1 -1
data/lib/reqcord/web.rb +122 -0
data/lib/reqcord.rb +4 -0
data/lib/tasks/reqcord.rake +26 -1
data/reqcord.gemspec +2 -1
metadata +14 -2

data/lib/reqcord/web.rb ADDED Viewed

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+require "rack/mime"
+module Reqcord
+  # Serves the generated documentation from inside the application, the way
+  # Sidekiq::Web does:
+  #
+  #   # config/routes.rb
+  #   mount Reqcord::Web => "/api-docs" if Rails.env.development?
+  #
+  # `/api-docs` renders the OpenAPI document with Scalar; every other path is
+  # a file from the output directory (`dataset.json`, `postman/collection.json`,
+  # the Markdown pages, the cURL scripts). Nothing is generated on request —
+  # run `bin/rails reqcord:generate` first.
+  class Web
+    SCALAR_SCRIPT = "https://cdn.jsdelivr.net/npm/@scalar/api-reference"
+    OPENAPI_PATH = "openapi/openapi.json"
+    class << self
+      # `mount Reqcord::Web => "/api-docs"` calls the class itself.
+      def call(env)
+        app.call(env)
+      end
+      def app
+        @app ||= new
+      end
+    end
+    def initialize(root: nil)
+      @root = root
+    end
+    def call(env)
+      path = Rack::Utils.unescape_path(env["PATH_INFO"].to_s)
+      return index(env) if path.empty? || path == "/"
+      file = resolve(path)
+      return not_found unless file
+      [200, { "content-type" => content_type(file) }, [File.binread(file)]]
+    end
+    private
+    def root
+      Pathname(@root || Reqcord.configuration.output_directory).expand_path
+    end
+    def index(env)
+      html = File.exist?(root.join(OPENAPI_PATH)) ? scalar_page(env) : empty_page(env)
+      [200, { "content-type" => "text/html; charset=utf-8" }, [html]]
+    end
+    # The path traversal guard: whatever the request says, the file must be
+    # inside the output directory.
+    def resolve(path)
+      candidate = root.join(path.delete_prefix("/")).expand_path
+      return nil unless candidate.to_s.start_with?("#{root}/")
+      return nil unless candidate.file?
+      candidate.to_s
+    end
+    def content_type(file)
+      case File.extname(file)
+      when ".md" then "text/markdown; charset=utf-8"
+      when ".sh" then "text/plain; charset=utf-8"
+      else Rack::Mime.mime_type(File.extname(file), "application/octet-stream")
+      end
+    end
+    def not_found
+      [404, { "content-type" => "text/plain" }, ["Not Found"]]
+    end
+    # Absolute links: the page is served at the mount point itself, so a
+    # relative `openapi/…` would resolve one level too high.
+    def base(env)
+      env["SCRIPT_NAME"].to_s.chomp("/")
+    end
+    def scalar_page(env)
+      <<~HTML
+        <!doctype html>
+        <html>
+          <head>
+            <meta charset="utf-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <title>API Reference</title>
+          </head>
+          <body>
+            <script id="api-reference" data-url="#{base(env)}/#{OPENAPI_PATH}"></script>
+            <script src="#{SCALAR_SCRIPT}"></script>
+          </body>
+        </html>
+      HTML
+    end
+    def empty_page(env)
+      <<~HTML
+        <!doctype html>
+        <html>
+          <head><meta charset="utf-8"><title>Reqcord</title></head>
+          <body style="font-family: system-ui, sans-serif; max-width: 40rem; margin: 4rem auto; line-height: 1.5">
+            <h1>No documentation generated yet</h1>
+            <p>Reqcord serves the files under <code>#{root}</code>. Generate them from your test suite:</p>
+            <pre>bin/rails reqcord:generate</pre>
+            <p>Then reload this page: the OpenAPI document is rendered here with Scalar, and
+            <a href="#{base(env)}/dataset.json">dataset.json</a>,
+            <a href="#{base(env)}/postman/collection.json">postman/collection.json</a> and the Markdown pages are served alongside it.</p>
+          </body>
+        </html>
+      HTML
+    end
+  end
+end

data/lib/reqcord.rb CHANGED Viewed

@@ -11,6 +11,7 @@ require "pathname"
 require_relative "reqcord/version"
 require_relative "reqcord/errors"
 require_relative "reqcord/support"
+require_relative "reqcord/file_value"
 require_relative "reqcord/configuration"
 require_relative "reqcord/request_example"
@@ -32,7 +33,10 @@ require_relative "reqcord/exporters"
 require_relative "reqcord/exporters/curl"
 require_relative "reqcord/exporters/markdown"
 require_relative "reqcord/exporters/postman"
+require_relative "reqcord/exporters/openapi"
 require_relative "reqcord/generator"
+require_relative "reqcord/check"
+require_relative "reqcord/web"
 require_relative "reqcord/railtie" if defined?(Rails::Railtie)

data/lib/tasks/reqcord.rake CHANGED Viewed

@@ -45,11 +45,13 @@ namespace :reqcord do
         include_uncovered: false
       # markdown: pages under docs/api, curl: one runnable .sh per endpoint,
-      # postman: postman/collection.json (import into Postman or Hoppscotch).
+      # postman: postman/collection.json (import into Postman or Hoppscotch),
+      # openapi: openapi/openapi.json (rendered with Scalar by Reqcord::Web).
       exporters:
         - curl
         - markdown
         - postman
+        - openapi
       variables:
         # Host of every generated cURL and the Postman `base_url` variable.
@@ -107,6 +109,29 @@ namespace :reqcord do
     puts "Output: #{Reqcord.configuration.output_directory}"
   end
+  desc "Fail when the committed documentation is behind the tests"
+  task check: :environment do
+    Reqcord.reload_configuration!
+    result =
+      Reqcord::Check.call(
+        resources: ENV.fetch("RESOURCE", "").split(",").map(&:strip).reject(&:empty?),
+        version: ENV["VERSION"].to_s.strip.then { |value| value.empty? ? nil : value }
+      )
+    output = Reqcord.configuration.output_directory
+    if result.clean?
+      puts "Reqcord: #{output} is up to date."
+    else
+      puts "Reqcord: #{output} is out of date."
+      puts
+      result.lines.each { |line| puts "  #{line}" }
+      puts
+      abort "Run `bin/rails reqcord:generate` and commit the result."
+    end
+  end
   desc "List the routes Reqcord would document"
   task routes: :environment do
     routes =

data/reqcord.gemspec CHANGED Viewed

@@ -20,7 +20,8 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.2"
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["changelog_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/master/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "#{spec.homepage}/tree/master/docs"
   spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["rubygems_mfa_required"] = "true"

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reqcord
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Ahmet Saridogan
@@ -145,7 +145,14 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/architecture.md
+- docs/capture.md
 - docs/configuration.md
+- docs/exporters.md
+- docs/getting-started.md
+- docs/route-coverage.md
+- docs/troubleshooting.md
+- docs/web.md
 - examples/reqcord.yml
 - gemfiles/rails_7.1.gemfile
 - gemfiles/rails_7.2.gemfile
@@ -158,6 +165,7 @@ files:
 - lib/reqcord/capture/minitest_context.rb
 - lib/reqcord/capture/rspec_context.rb
 - lib/reqcord/capture/test_context.rb
+- lib/reqcord/check.rb
 - lib/reqcord/configuration.rb
 - lib/reqcord/dataset.rb
 - lib/reqcord/endpoint.rb
@@ -165,7 +173,9 @@ files:
 - lib/reqcord/exporters.rb
 - lib/reqcord/exporters/curl.rb
 - lib/reqcord/exporters/markdown.rb
+- lib/reqcord/exporters/openapi.rb
 - lib/reqcord/exporters/postman.rb
+- lib/reqcord/file_value.rb
 - lib/reqcord/generator.rb
 - lib/reqcord/railtie.rb
 - lib/reqcord/renderers/curl.rb
@@ -177,6 +187,7 @@ files:
 - lib/reqcord/schema.rb
 - lib/reqcord/support.rb
 - lib/reqcord/version.rb
+- lib/reqcord/web.rb
 - lib/tasks/reqcord.rake
 - reqcord.gemspec
 homepage: https://github.com/ahmetsaridogan/reqcord
@@ -184,7 +195,8 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/ahmetsaridogan/reqcord
-  changelog_uri: https://github.com/ahmetsaridogan/reqcord
+  changelog_uri: https://github.com/ahmetsaridogan/reqcord/blob/master/CHANGELOG.md
+  documentation_uri: https://github.com/ahmetsaridogan/reqcord/tree/master/docs
   source_code_uri: https://github.com/ahmetsaridogan/reqcord
   rubygems_mfa_required: 'true'
 rdoc_options: []