reqcord 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b5479eb9ebc313b6b16250eb40692a664c4d7f56eba83a5875a061153714941
-  data.tar.gz: 61a8fa46ddcef53e0e318589d94fd485e25f7666a3042d2050d05138350db83b
+  metadata.gz: 2e075e88e6b448b287ccc4b845cf82b0e18d4d7b9778a8e82d1c09f798d2b1f8
+  data.tar.gz: 6a395b1ab6f789b184a72c63b14f9873f2465e891f96ade6c91b19cc102211a5
 SHA512:
-  metadata.gz: 3794123441aba25e1aa5a0fd5560ef280cda236ce4eee98b939f684d2cb40a6833b82358331cdf5a609b18076112901b7b9cefa623bea10145350a5d6f729205
-  data.tar.gz: 5b416b598625d8f76df50cdce032eafddd6102f0a00f364231f334c7d3939041b2e5d622adb801ee3e04ef00d61936ab0c75b1850c3018445954e78ea8236869
+  metadata.gz: f5c43bee1cdcbe7d6d6b3de653027a5704995bd9ddd602e879c6905e0a1fdb27ca1936d55ad11be42b1d1969c925ceaf519e5c193f7d86c787b0d8f6f02eba28
+  data.tar.gz: f80362f26eddd01297d81f62080e0b93ae50742d49c1616ec92b940550a5a7b3e63e33d69b427cd9e8c7a3091c78c3cffaaae58fc15db13ec0cdc8a18ce01299

data/CHANGELOG.md

@@ -1,6 +1,34 @@
 # Changelog
 
-## [0.1.3] - Unreleased
+## [0.2.0] - Unreleased
+
+### Added
+
+* OpenAPI 3.1 exporter (`openapi/openapi.json`, on by default): one path item
+  per documented route (`/items(/:id)` becomes `/items` and `/items/{id}`),
+  parameters and request bodies from the inferred schemas, one response per
+  captured status with its example, bearer / API-key security schemes from
+  the sanitized headers.
+* `Reqcord::Web`: `mount Reqcord::Web => "/api-docs"` serves the OpenAPI
+  document with Scalar and every other generated file (`dataset.json`, the
+  Postman collection, Markdown pages, cURL scripts) from inside the
+  application, Sidekiq::Web style.
+
+## [0.1.4] - 2026-09-16
+
+### Changed
+
+* A failing test run no longer discards the output. The docs are generated
+  from what the suite captured, the warning names the exit status and the
+  report points out that routes reached only by failing tests are listed as
+  uncovered. The previous behaviour is `test.strict: true`.
+
+### Added
+
+* `test.strict` (`REQCORD_STRICT=1`): abort on a failing suite instead of
+  documenting what it captured.
+
+## [0.1.3] - 2026-09-16
 
 ### Added
 

data/README.md

@@ -21,7 +21,7 @@ Minitest Integration Tests
           ↓
    Canonical Dataset
           ↓
-   Markdown · cURL · Postman
+   Markdown · cURL · Postman · OpenAPI (Scalar)
 ```
 
 ## Why Reqcord?
@@ -172,8 +172,10 @@ The parameter tables are inferred from the requests the application
 **accepted**: two passing tests sent `"active"` and `"passive"`, a third sent
 `"inactive"` and got a `422`, so the documentation lists the two values that
 work and keeps the rejection only as a response example. The same run also
-writes a runnable `curl/api/v2/customers/create.sh` and a Postman collection
-with this request and its three saved responses.
+writes a runnable `curl/api/v2/customers/create.sh`, a Postman collection
+with this request and its three saved responses, and an OpenAPI 3.1 document
+you can browse with Scalar by mounting `Reqcord::Web` (see
+[Serve the docs in your app](#serve-the-docs-in-your-app)).
 
 ## Examples
 
@@ -205,9 +207,9 @@ Minitest ──────► Test Adapter
                        ▼
                 Reqcord Dataset
                        │
-          ┌────────────┼────────────┐
-          ▼            ▼            ▼
-      Markdown       cURL        Postman
+          ┌────────────┼────────────┬────────────┐
+          ▼            ▼            ▼            ▼
+      Markdown       cURL        Postman      OpenAPI ──► Scalar
 ```
 
 The internal dataset is framework-independent and output-independent.
@@ -277,6 +279,7 @@ exporters:
   - curl
   - markdown
   - postman
+  - openapi
 
 variables:
   base_url: http://localhost:3000
@@ -401,8 +404,10 @@ docs/api/
 │   └── api/v2/customers/
 │       ├── create.sh
 │       └── show.sh
-└── postman/
-    └── collection.json
+├── postman/
+│   └── collection.json
+└── openapi/
+    └── openapi.json
 ```
 
 `dataset.json` contains Reqcord's normalized representation of the captured
@@ -446,6 +451,50 @@ they are counted as *skipped* in the report rather than dropped.
 Hoppscotch imports Postman v2.1 collections directly: *Import → Postman* and
 point it at the same file.
 
+## OpenAPI
+
+`openapi/openapi.json` is an OpenAPI 3.1 document built from the same dataset:
+
+* one path item per documented route, in OpenAPI notation — `/customers/:id`
+  becomes `/customers/{id}`, and `/items(/:id)` becomes both `/items` and
+  `/items/{id}`,
+* path and query parameters from the inferred schemas, closed value sets as
+  `enum`,
+* a `requestBody` (`application/json` or `application/x-www-form-urlencoded`,
+  whichever the test sent) whose JSON Schema is rebuilt from the field paths,
+  nested objects and arrays included, `required` from what every accepted
+  request carried,
+* one response per captured status with its schema and example,
+* `bearerAuth` / `apiKeyAuth` security schemes derived from the sanitized
+  `Authorization` and `X-Api-Key` headers, applied per operation — so public
+  endpoints stay public.
+
+Anything that reads OpenAPI (Scalar, Swagger UI, Redoc, code generators) can
+consume the file as is.
+
+## Serve the docs in your app
+
+`Reqcord::Web` is a Rack application that serves the generated output from
+inside the Rails app, the way `Sidekiq::Web` does:
+
+```ruby
+# config/routes.rb
+mount Reqcord::Web => "/api-docs" if Rails.env.development?
+```
+
+* `/api-docs` renders `openapi/openapi.json` with
+  [Scalar](https://scalar.com) — a searchable reference with a *Try it*
+  client, loaded from the Scalar CDN,
+* `/api-docs/openapi/openapi.json`, `/api-docs/dataset.json`,
+  `/api-docs/postman/collection.json`, `/api-docs/api/v2/customers/create.md`,
+  `/api-docs/curl/api/v2/customers/create.sh` … serve the generated files,
+* nothing outside `output.directory` is ever served.
+
+`Reqcord::Web` only reads; run `bin/rails reqcord:generate` first (before the
+first run the page tells you so). Because the files are static, mounting it
+in production is a deployment decision, not a Reqcord one — guard it as you
+would any internal page.
+
 ## Request Capture
 
 Reqcord captures HTTP information from Rails integration tests.
@@ -651,10 +700,13 @@ Reqcord
 │   ├── Payload          (JSON vs form, nested query flattening)
 │   └── Curl
 │
-└── Exporters
-    ├── Markdown
-    ├── Curl             (one .sh per endpoint)
-    └── Postman          (Collection v2.1, also for Hoppscotch)
+├── Exporters
+│   ├── Markdown
+│   ├── Curl             (one .sh per endpoint)
+│   ├── Postman          (Collection v2.1, also for Hoppscotch)
+│   └── Openapi          (OpenAPI 3.1)
+│
+└── Web                  (Rack app: Scalar page + generated files)
 ```
 
 Test adapters are responsible only for converting test execution into Reqcord's canonical model.
@@ -667,7 +719,7 @@ Minitest ──┐
 RSpec ─────┼──► Dataset ──► Markdown
            │             ├─► cURL
 Other ─────┘             ├─► Postman  (→ Hoppscotch)
-                         └─► OpenAPI  (0.2)
+                         └─► OpenAPI  (→ Scalar via Reqcord::Web)
 ```
 
 ## v0.1 Scope
@@ -689,6 +741,7 @@ The first Reqcord release focuses on proving the capture pipeline.
 * Markdown documentation
 * Generated cURL requests (in the Markdown and as runnable `.sh` files)
 * Postman Collection v2.1 (imports into Hoppscotch as well)
+* OpenAPI 3.1 document, browsable with Scalar through `mount Reqcord::Web`
 * The whole route table: custom actions, `match via:`, `via: :all`,
   singular resources, optional segments and globs, mounted engines
 * Resource filtering
@@ -696,8 +749,6 @@ The first Reqcord release focuses on proving the capture pipeline.
 
 ### Not included yet
 
-* OpenAPI generation
-* Scalar integration
 * Multipart requests
 * CI documentation drift detection
 
@@ -705,24 +756,6 @@ These features belong to later releases rather than expanding the initial scope.
 
 ## Roadmap
 
-### v0.2
-
-OpenAPI 3.1 export and Scalar integration.
-
-```text
-Reqcord Dataset
-      ↓
-OpenAPI 3.1
-      ↓
-Scalar
-```
-
-This will allow a development application to expose documentation such as:
-
-```text
-http://localhost:3000/api-docs
-```
-
 ### v0.3
 
 Rack::Test capture, so frameworks other than Rails (Sinatra, Roda, Hanami) can
@@ -767,7 +800,7 @@ Reqcord is currently in early development.
 
 The initial goal is intentionally narrow:
 
-> Capture real Rails API requests and responses from the test suite and generate accurate, sanitized Markdown documentation, executable cURL examples and a Postman collection — without the developer writing any of them by hand.
+> Capture real Rails API requests and responses from the test suite and generate accurate, sanitized Markdown documentation, executable cURL examples, a Postman collection and an OpenAPI document — without the developer writing any of them by hand.
 
 Once that pipeline is reliable, additional adapters and exporters can be built on top of the same dataset.
 

data/docs/configuration.md

@@ -52,6 +52,7 @@ before any test runs. YAML aliases are disabled.
 | --- | --- |
 | `REQCORD_TEST_FRAMEWORK` | `test.framework` |
 | `REQCORD_TEST_COMMAND` | `test.command` (and therefore `test.paths`) |
+| `REQCORD_STRICT` | `test.strict` (`1` or `true`) |
 | `REQCORD_OUTPUT` | `output.directory` |
 | `REQCORD_BASE_URL` | `variables.base_url` |
 | `RESOURCE`, `VERSION` | run-time filters, see [Filtering a run](#filtering-a-run) |
@@ -123,9 +124,23 @@ absent.
 
 With neither `paths` nor `command`, Reqcord runs `bin/rails test`.
 
-Whatever runs must exit successfully. A failing suite aborts the run with
-`Reqcord::GenerationError` and nothing is written — documentation is only
-generated from a green suite.
+### `test.strict`
+
+Default `false`. What happens when the suite does not exit successfully:
+
+* `false` — the run continues and documents what the tests captured. A
+  warning names the exit status, and the report reminds you that routes
+  exercised only by failing tests show up as *uncovered*. A test that failed
+  on an assertion after its request got a `2xx` still counts: the request
+  and response are what the application really did.
+* `true` (or `REQCORD_STRICT=1`) — a failing suite aborts the run with
+  `Reqcord::GenerationError` and nothing is written. Use it in CI when the
+  generated docs are an artifact that must come from a green build.
+
+```yaml
+test:
+  strict: true
+```
 
 ---
 
@@ -214,17 +229,41 @@ pages as well, each carrying a note that nothing was captured.
 
 ## `exporters`
 
-Which outputs to write. Default: all three.
+Which outputs to write. Default: all four.
 
 | Name | Writes |
 | --- | --- |
 | `markdown` | `README.md` plus one page per endpoint: headers, typed parameter tables, example request, cURL, one example and field table per response status |
 | `curl` | one runnable `.sh` per endpoint under `curl/`, built from the successful captured request |
 | `postman` | `postman/collection.json`, a Postman Collection v2.1 — folders per controller namespace, one request per endpoint, every captured status saved as an example, placeholders as collection variables, bearer auth at collection level. Hoppscotch imports the same file |
+| `openapi` | `openapi/openapi.json`, an OpenAPI 3.1 document — one path item per documented route (`/items(/:id)` becomes `/items` and `/items/{id}`), parameters and request body schemas rebuilt from the inferred fields, one response per captured status with schema and example, `bearerAuth` / `apiKeyAuth` security schemes from the sanitized headers. `servers` comes from `variables.base_url` |
 
 `dataset.json` is always written. An unknown name raises
 `Reqcord::ConfigurationError` before any test runs.
 
+### Browsing the output: `Reqcord::Web`
+
+The generated directory can be served from the application itself:
+
+```ruby
+# config/routes.rb
+mount Reqcord::Web => "/api-docs" if Rails.env.development?
+```
+
+`/api-docs` renders the OpenAPI document with Scalar (loaded from
+`cdn.jsdelivr.net`); every other path under the mount is a file from
+`output.directory` — `openapi/openapi.json`, `dataset.json`,
+`postman/collection.json`, the Markdown pages, the cURL scripts. Requests
+that resolve outside that directory get a `404`. Nothing is generated on the
+fly: run `bin/rails reqcord:generate` first, and again after the tests change.
+
+`Reqcord::Web` reads `output.directory` from `reqcord.yml` (and
+`REQCORD_OUTPUT`). To serve a different directory, mount an instance instead:
+
+```ruby
+mount Reqcord::Web.new(root: Rails.root.join("public/api-docs")) => "/api-docs"
+```
+
 ---
 
 ## `variables`

data/examples/reqcord.yml

@@ -19,6 +19,11 @@ test:
   # Or spell the command out yourself; it wins over `paths`. Globs expand.
   # command: bin/rails test test/integration test/api
 
+  # A failing suite still documents what it captured; routes reached only by
+  # failing tests are listed as uncovered. `true` aborts instead
+  # (REQCORD_STRICT=1 per run).
+  # strict: false
+
 routes:
   # Only routes under this prefix are documented; a list works too:
   #   prefix: [/api, /partner]
@@ -35,11 +40,13 @@ output:
   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 — mount Reqcord::Web to browse it with Scalar.
 exporters:
   - curl
   - markdown
   - postman
+  - openapi
 
 variables:
   # Used as the host in every generated cURL and as the Postman `base_url`

data/lib/reqcord/configuration.rb

@@ -8,7 +8,11 @@ module Reqcord
       # No default command: with neither `command` nor `paths` the generator
       # falls back to `bin/rails test`, and `paths` alone must be able to win.
       "test" => {
-        "framework" => "minitest"
+        "framework" => "minitest",
+
+        # A red suite still documents what its green tests captured; strict
+        # runs abort instead, for CI that treats the docs as an artifact.
+        "strict" => false
       },
 
       "routes" => {
@@ -23,7 +27,7 @@ module Reqcord
         "include_uncovered" => false
       },
 
-      "exporters" => %w[curl markdown postman],
+      "exporters" => %w[curl markdown postman openapi],
 
       "variables" => {
         "base_url" => "http://localhost:3000"
@@ -123,6 +127,13 @@ module Reqcord
       Array(data.dig("test", "paths")).map(&:to_s)
     end
 
+    # Abort on a failing suite instead of documenting what was captured.
+    def strict_tests?
+      value = ENV.fetch("REQCORD_STRICT") { data.dig("test", "strict") }
+
+      [true, "true", "1"].include?(value)
+    end
+
     # `prefix: /api` or `prefix: [/v1, /v2]`; a route under any of them is
     # documented. Empty means every route.
     def route_prefixes

data/lib/reqcord/exporters/openapi.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Exporters
+    # Writes an OpenAPI 3.1 document (`openapi/openapi.json`) from the dataset:
+    # one path item per documented route, parameters and request bodies from
+    # the inferred schemas, one response per captured status with its example,
+    # and security schemes derived from the sanitized credential headers. This
+    # is what Scalar (via Reqcord::Web), Swagger UI or Redoc render.
+    class Openapi
+      OPENAPI_VERSION = "3.1.0"
+      DYNAMIC_SEGMENT = /[:*]([a-zA-Z_][a-zA-Z0-9_]*)/
+      BEARER = /\ABearer\s+/i
+
+      def self.call(dataset:, output_dir:, configuration:)
+        new(
+          dataset: dataset,
+          output_dir: output_dir,
+          configuration: configuration
+        ).call
+      end
+
+      def initialize(dataset:, output_dir:, configuration:)
+        @dataset = dataset
+        @output_dir = Pathname(output_dir).join("openapi")
+        @configuration = configuration
+      end
+
+      def call
+        FileUtils.mkdir_p(output_dir)
+
+        path = output_dir.join("openapi.json")
+        File.write(path, "#{JSON.pretty_generate(document)}\n")
+
+        [path.to_s]
+      end
+
+      def document
+        {
+          openapi: OPENAPI_VERSION,
+          info: {
+            title: "#{File.basename(configuration.root.to_s)} API",
+            version: api_version,
+            description: "Generated by Reqcord from the application's integration tests."
+          },
+          servers: [{ url: configuration.base_url }],
+          tags: tags,
+          paths: paths,
+          components: components
+        }.reject { |_key, value| value.nil? || (value.respond_to?(:empty?) && value.empty?) }
+      end
+
+      private
+
+      attr_reader :dataset, :output_dir, :configuration
+
+      # A single API version across the dataset names the document; mixed
+      # versions fall back to a neutral one.
+      def api_version
+        versions = dataset.curl_ready_endpoints.map(&:api_version).compact.uniq
+
+        versions.size == 1 ? versions.first : "1.0.0"
+      end
+
+      def tags
+        dataset.resources
+               .select { |resource| resource.endpoints.any?(&:curl_ready?) }
+               .map { |resource| { name: resource.title, description: resource.name }.compact }
+      end
+
+      def paths
+        dataset.resources.each_with_object({}) do |resource, result|
+          resource.endpoints.each do |endpoint|
+            next unless endpoint.curl_ready?
+            next if endpoint.method == RouteCollector::ANY
+
+            path_variants(endpoint.path).each do |oas_path|
+              result[oas_path] ||= {}
+              result[oas_path][endpoint.method.downcase] = operation(endpoint, oas_path, resource)
+            end
+          end
+        end
+      end
+
+      # `/items(/:id)` is two OpenAPI paths: `/items` and `/items/{id}`.
+      def path_variants(pattern)
+        required = pattern.gsub(/\([^()]*\)/, "")
+        expanded = pattern.tr("()", "")
+
+        [required, expanded].uniq.map { |path| path.gsub(DYNAMIC_SEGMENT, '{\1}') }
+      end
+
+      def operation(endpoint, oas_path, resource)
+        example = endpoint.primary_request_example
+
+        {
+          operationId: operation_id(endpoint, oas_path),
+          summary: endpoint.name,
+          description: description(endpoint),
+          tags: [resource.title],
+          parameters: path_parameters(endpoint, oas_path) + query_parameters(endpoint),
+          requestBody: request_body(endpoint, example),
+          responses: responses(endpoint),
+          security: security_for(example)
+        }.reject { |_key, value| value.nil? || (value.respond_to?(:empty?) && value.empty?) }
+      end
+
+      def operation_id(endpoint, oas_path)
+        Support.parameterize("#{endpoint.method} #{oas_path.tr('{}', '')}").tr("-", "_")
+      end
+
+      def description(endpoint)
+        lines = ["#{endpoint.controller}##{endpoint.action}"]
+        lines << "Also answers #{endpoint.also_methods.join(', ')}." unless endpoint.also_methods.empty?
+        lines << "Route: #{endpoint.route_name}" if endpoint.route_name
+
+        lines.join("\n")
+      end
+
+      def path_parameters(endpoint, oas_path)
+        oas_path.scan(/\{([^}]+)\}/).flatten.map do |name|
+          field = endpoint.path_param_schema[name]
+
+          {
+            name: name,
+            in: "path",
+            required: true,
+            schema: field ? scalar_schema(field) : { type: "string" },
+            example: field&.example
+          }.compact
+        end
+      end
+
+      # `filter.category` was captured as Rails' `filter[category]`.
+      def query_parameters(endpoint)
+        endpoint.query_schema.map do |field|
+          {
+            name: query_name(field.path),
+            in: "query",
+            required: field.required?,
+            schema: scalar_schema(field),
+            example: field.example
+          }.compact
+        end
+      end
+
+      def query_name(path)
+        head, *rest = path.split(".")
+
+        head + rest.map { |segment| "[#{segment}]" }.join
+      end
+
+      def request_body(endpoint, example)
+        return nil if endpoint.body_schema.empty?
+
+        content_type = Renderers::Payload.json?(example) ? "application/json" : "application/x-www-form-urlencoded"
+
+        {
+          required: true,
+          content: {
+            content_type => { schema: json_schema(endpoint.body_schema), example: example.body }.compact
+          }
+        }
+      end
+
+      def responses(endpoint)
+        endpoint.responses.each_with_object({}) do |response, result|
+          example = response.example
+          entry = { description: example.status_text }
+
+          if example.body?
+            content_type = example.content_type.to_s.empty? ? "application/json" : example.content_type
+            entry[:content] = { content_type => { schema: json_schema(response.schema), example: example.body }.compact }
+          end
+
+          result[response.status.to_s] = entry
+        end
+      end
+
+      # --- schemas ----------------------------------------------------------
+
+      # Turns the flattened field list (`customer.items[].sku`) back into a
+      # JSON Schema tree. A leaf every accepted request carried is required,
+      # and so is every object on the way down to it.
+      def json_schema(schema)
+        return nil if schema.empty?
+
+        root = {}
+
+        schema.each do |field|
+          node = root
+
+          segments_for(field.path).each do |segment|
+            if segment == :array
+              node[:type] = "array"
+              node[:items] ||= {}
+              node = node[:items]
+            else
+              node[:type] = "object"
+              node[:properties] ||= {}
+              node[:properties][segment] ||= {}
+              node[:required] = (node[:required] || []) | [segment] if field.required?
+              node = node[:properties][segment]
+            end
+          end
+
+          node.merge!(scalar_schema(field)) if node.empty?
+        end
+
+        root
+      end
+
+      # "customer.items[].sku" -> ["customer", "items", :array, "sku"];
+      # "[].id" -> [:array, "id"]
+      def segments_for(path)
+        path.split(".").flat_map do |part|
+          name, brackets = part.match(/\A([^\[\]]*)((?:\[\])*)\z/).captures
+          pieces = []
+          pieces << name unless name.empty?
+          pieces.concat([:array] * (brackets.length / 2))
+          pieces
+        end
+      end
+
+      def scalar_schema(field)
+        types = field.types.to_a.sort
+        schema = { type: types.size == 1 ? types.first : types }
+        schema[:enum] = field.listed_values if field.enum?
+        schema[:example] = field.example unless field.example.nil?
+
+        schema
+      end
+
+      # --- security ---------------------------------------------------------
+
+      def components
+        schemes = {}
+        schemes[:bearerAuth] = { type: "http", scheme: "bearer" } if bearer_used?
+        schemes[:apiKeyAuth] = { type: "apiKey", in: "header", name: api_key_header } if api_key_header
+
+        schemes.empty? ? nil : { securitySchemes: schemes }
+      end
+
+      def security_for(example)
+        requirements = []
+        requirements << { bearerAuth: [] } if bearer?(example)
+        requirements << { apiKeyAuth: [] } if api_key_header && header(example, api_key_header)
+
+        requirements
+      end
+
+      def bearer_used?
+        documented_examples.any? { |example| bearer?(example) }
+      end
+
+      def bearer?(example)
+        header(example, "Authorization").to_s.match?(BEARER)
+      end
+
+      # The first API-key style header the sanitizer knows about that a
+      # documented request actually carried.
+      def api_key_header
+        return @api_key_header if defined?(@api_key_header)
+
+        candidates = configuration.sanitized_headers.keys.reject { |name| name.casecmp?("Authorization") }
+
+        @api_key_header = candidates.find do |name|
+          documented_examples.any? { |example| header(example, name) }
+        end
+      end
+
+      def header(example, name)
+        example.headers.find { |key, _| key.to_s.casecmp?(name) }&.last
+      end
+
+      def documented_examples
+        @documented_examples ||= dataset.curl_ready_endpoints.map(&:primary_request_example)
+      end
+    end
+
+    register("openapi", Openapi)
+  end
+end

data/lib/reqcord/generator.rb

@@ -56,6 +56,14 @@ module Reqcord
     # run can say why a request did not turn into documentation.
     attr_reader :unmatched_paths
 
+    # Exit status of the test run, so a caller can tell a fully green run
+    # from documentation generated out of a partly failing suite.
+    attr_reader :test_status
+
+    def tests_passed?
+      test_status.nil? || test_status.success?
+    end
+
     # Routes seen in the table but not documentable, by reason (redirect,
     # mount). Set by collect_routes; exposed so a run can be reconciled.
     attr_accessor :skipped_routes
@@ -161,6 +169,10 @@ module Reqcord
         Reqcord.log("skipped #{skipped_total} route(s) that cannot be documented: #{reasons}")
       end
 
+      unless tests_passed?
+        Reqcord.warn("the test run failed: routes exercised only by failing tests are listed as uncovered")
+      end
+
       return if unmatched_paths.empty?
 
       shown = unmatched_paths.uniq.first(5)
@@ -254,10 +266,19 @@ module Reqcord
           wait_thread.value
         end
 
+      @test_status = status
+
       return if status.success?
 
-      raise GenerationError,
-            "Test suite failed while generating Reqcord documentation"
+      if configuration.strict_tests?
+        raise GenerationError,
+              "Test suite failed while generating Reqcord documentation (test.strict is on)"
+      end
+
+      # A red suite still tells the truth about the requests that passed;
+      # dropping everything would hide the docs behind an unrelated failure.
+      Reqcord.warn("test run exited with status #{status.exitstatus}; documenting what it captured anyway")
+      Reqcord.warn("  set test.strict: true (or REQCORD_STRICT=1) to abort on a failing suite")
     end
 
     def read_exchanges(capture_file)

data/lib/reqcord/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Reqcord
-  VERSION = "0.1.3"
+  VERSION = "0.2.0"
 end

data/lib/reqcord/web.rb

@@ -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

@@ -32,7 +32,9 @@ 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/web"
 
 require_relative "reqcord/railtie" if defined?(Rails::Railtie)
 

data/lib/tasks/reqcord.rake

@@ -27,6 +27,10 @@ namespace :reqcord do
         # Or spell the command out yourself; it wins over `paths`.
         # command: bin/rails test test/integration test/api
 
+        # A failing suite still documents what it captured. Set true to abort
+        # instead (or run with REQCORD_STRICT=1).
+        # strict: false
+
       routes:
         # Only routes under this prefix are documented; a list works too
         # (`prefix: [/v1, /v2]`). Filter a single run with
@@ -41,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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reqcord
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Ahmet Saridogan
@@ -165,6 +165,7 @@ 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/generator.rb
 - lib/reqcord/railtie.rb
@@ -177,6 +178,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