reqcord 0.1.0 → 0.1.1

data/lib/reqcord/exporters/markdown.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Exporters
+    class Markdown
+      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)
+        @configuration = configuration
+      end
+
+      # Returns every written path.
+      def call
+        FileUtils.mkdir_p(output_dir)
+
+        written = [write(output_dir.join("README.md"), index_document)]
+
+        written_resources.each do |resource|
+          directory = output_dir.join(resource.slug)
+
+          FileUtils.mkdir_p(directory)
+
+          written << write(
+            directory.join("index.md"),
+            resource_document(resource)
+          )
+
+          filenames(resource).each do |endpoint, filename|
+            next unless documented?(endpoint)
+
+            written << write(
+              directory.join(filename),
+              endpoint_document(resource, endpoint)
+            )
+          end
+        end
+
+        written
+      end
+
+      private
+
+      attr_reader :dataset, :output_dir, :configuration
+
+      # An endpoint gets a page when a test reached it, or when the project
+      # asked for the gaps to be written out too.
+      def documented?(endpoint)
+        endpoint.curl_ready? || configuration.include_uncovered?
+      end
+
+      # A resource with nothing to show gets no directory, so the index never
+      # links to a page that was not written.
+      def written_resources
+        @written_resources ||= dataset.resources.select do |resource|
+          resource.endpoints.any? { |endpoint| documented?(endpoint) }
+        end
+      end
+
+      def written?(resource)
+        written_resources.include?(resource)
+      end
+
+      def write(path, content)
+        File.write(path, content)
+
+        path.to_s
+      end
+
+      def filenames(resource)
+        resource.file_basenames.transform_values { |basename| "#{basename}.md" }
+      end
+
+      def index_document
+        lines = ["# API Documentation", ""]
+        lines << "Generated by Reqcord from the application's integration tests."
+        lines << ""
+        lines << "Base URL: `#{configuration.base_url}`"
+        lines << ""
+        lines.concat(placeholders_section)
+
+        dataset.resources.each do |resource|
+          lines << if written?(resource)
+                     "## [#{resource.title}](#{resource.slug}/index.md)"
+                   else
+                     "## #{resource.title}"
+                   end
+          lines << ""
+          lines.concat(namespace_line(resource))
+          lines.concat(endpoint_table(resource, prefix: "#{resource.slug}/"))
+          lines << ""
+        end
+
+        undocumented = dataset.endpoints.reject(&:curl_ready?)
+
+        unless undocumented.empty?
+          lines << "## No Successful Request Captured"
+          lines << ""
+          lines << "No successful 2xx request was captured for these routes:"
+          lines << ""
+          undocumented.each { |endpoint| lines << "- `#{endpoint.method} #{endpoint.path}`" }
+          lines << ""
+        end
+
+        lines.join("\n")
+      end
+
+      # Sanitized values are written as placeholders; the reader has to know
+      # what to substitute.
+      def placeholders_section
+        placeholders = configuration.sanitized_headers.values.grep(/\{\{.+\}\}/)
+
+        return [] if placeholders.empty?
+
+        rows = configuration.sanitized_headers.filter_map do |header, value|
+          "| #{header} | `#{value}` |" if value.to_s.match?(/\{\{.+\}\}/)
+        end
+
+        ["## Placeholders", "", "| Header | Replace with |", "| --- | --- |", *rows, ""]
+      end
+
+      # Two resources can share a title (admin/customers, api/v2/customers);
+      # the namespace tells them apart.
+      def namespace_line(resource)
+        return [] if resource.namespace.empty?
+
+        ["Namespace: `#{resource.namespace}`", ""]
+      end
+
+      def resource_document(resource)
+        lines = ["# #{resource.title}", ""]
+        lines.concat(namespace_line(resource))
+
+        versions = resource.api_versions
+
+        unless versions.empty?
+          lines << "API version: #{versions.map { |version| "`#{version}`" }.join(', ')}"
+          lines << ""
+        end
+
+        lines.concat(endpoint_table(resource))
+        lines << ""
+        lines.join("\n")
+      end
+
+      def endpoint_table(resource, prefix: "")
+        rows = filenames(resource).map do |endpoint, filename|
+          path =
+            if documented?(endpoint)
+              "[`#{endpoint.path}`](#{prefix}#{filename})"
+            else
+              "`#{endpoint.path}`"
+            end
+
+          covered = endpoint.curl_ready? ? "" : " _(no successful request captured)_"
+
+          "| `#{endpoint.method}` | #{path} | #{endpoint.name}#{covered} |"
+        end
+
+        ["| Method | Path | Description |", "| --- | --- | --- |", *rows]
+      end
+
+      def endpoint_document(resource, endpoint)
+        example = endpoint.primary_request_example
+
+        lines = ["# #{endpoint.name}", "", endpoint_line(endpoint), ""]
+        lines.concat(namespace_line(resource))
+
+        unless endpoint.curl_ready?
+          lines << "_No successful 2xx request was captured for this endpoint yet._"
+          lines << ""
+        end
+
+        lines.concat(headers_section(example))
+        lines.concat(schema_section("Path Parameters", endpoint.path_param_schema))
+        lines.concat(schema_section("Query Parameters", endpoint.query_schema))
+        lines.concat(schema_section("Body Parameters", endpoint.body_schema))
+        lines.concat(request_body_section(example))
+        lines.concat(curl_section(example))
+        lines.concat(responses_section(endpoint))
+        lines.concat(["---", "", "Resource: [#{resource.title}](index.md)", ""])
+
+        lines.join("\n")
+      end
+
+      # Field, type, whether every accepted request carried it, and the values
+      # those requests used. Values are listed only when they look like a
+      # closed set; otherwise one of them stands as an example.
+      def schema_section(title, schema, level: 2)
+        return [] if schema.empty?
+
+        rows = schema.map do |field|
+          "| `#{field.path}` | #{field.type} | #{field.required? ? 'yes' : 'no'} | #{values_cell(field)} |"
+        end
+
+        ["#{'#' * level} #{title}", "", "| Field | Type | Required | Values |", "| --- | --- | --- | --- |", *rows, ""]
+      end
+
+      def values_cell(field)
+        return "-" if field.values.empty?
+        return field.listed_values.map { |value| "`#{value.inspect}`" }.join(" \\| ") if field.enum?
+
+        "`#{field.example.inspect}`"
+      end
+
+      # `PATCH /api/cart` (also `PUT`)
+      def endpoint_line(endpoint)
+        line = "`#{endpoint.method} #{endpoint.path}`"
+
+        return line if endpoint.also_methods.empty?
+
+        "#{line} (also #{endpoint.also_methods.map { |method| "`#{method}`" }.join(', ')})"
+      end
+
+      def headers_section(example)
+        return [] if example.nil? || example.headers.empty?
+
+        rows = example.headers.map { |name, value| "| #{name} | `#{value}` |" }
+
+        ["## Headers", "", "| Header | Value |", "| --- | --- |", *rows, ""]
+      end
+
+      # A form body is shown as the key/value structure the test built, which
+      # reads better than the encoded string; the note says how it travels.
+      def request_body_section(example)
+        return [] unless example&.body?
+
+        lines = ["## Example Request", ""]
+
+        unless Renderers::Payload.json?(example) || example.content_type.to_s.empty?
+          lines << "Sent as `#{example.content_type}`; the cURL below carries it in that encoding."
+          lines << ""
+        end
+
+        lines.concat([*code_block(example.body, example.content_type), ""])
+      end
+
+      def curl_section(example)
+        return [] if example.nil?
+
+        ["## cURL", "", "```bash", curl_for(example), "```", ""]
+      end
+
+      def responses_section(endpoint)
+        return [] if endpoint.response_examples.empty?
+
+        lines = ["## Responses", ""]
+
+        endpoint.responses.each do |response|
+          lines << "### #{response.example.title}"
+          lines << ""
+          lines.concat(schema_section("Fields", response.schema, level: 4))
+          lines.concat(response_body(response.example))
+        end
+
+        lines
+      end
+
+      def response_body(example)
+        return ["_No response body._", ""] unless example.body?
+
+        [*code_block(example.body, example.content_type), ""]
+      end
+
+      def curl_for(example)
+        Renderers::Curl.call(
+          example,
+          base_url: configuration.base_url
+        )
+      end
+
+      def code_block(value, content_type)
+        case value
+        when Hash, Array then ["```json", pretty_json(value), "```"]
+        else ["```#{content_type.to_s.include?('json') ? 'json' : 'text'}", value.to_s, "```"]
+        end
+      end
+
+      def pretty_json(value)
+        JSON.pretty_generate(value)
+      rescue JSON::GeneratorError
+        value.to_s
+      end
+    end
+
+    register("markdown", Markdown)
+  end
+end

data/lib/reqcord/exporters/postman.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Reqcord
+  module Exporters
+    # Writes a Postman Collection v2.1 (`postman/collection.json`). Folders
+    # follow the controller namespaces, each documented endpoint is one request
+    # built from the successful captured example, and every captured status
+    # is saved as a response example. Hoppscotch imports the same file.
+    class Postman
+      SCHEMA_URL = "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+      PLACEHOLDER = /\{\{([A-Za-z0-9_]+)\}\}/
+      BEARER = /\ABearer\s+\{\{([A-Za-z0-9_]+)\}\}\z/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("postman")
+        @configuration = configuration
+      end
+
+      def call
+        FileUtils.mkdir_p(output_dir)
+
+        path = output_dir.join("collection.json")
+        File.write(path, "#{JSON.pretty_generate(collection)}\n")
+
+        [path.to_s]
+      end
+
+      def collection
+        {
+          info: {
+            name: "#{File.basename(configuration.root.to_s)} API",
+            description: "Generated by Reqcord from the application's integration tests.",
+            schema: SCHEMA_URL
+          },
+          item: folders,
+          variable: variables,
+          auth: auth
+        }.compact
+      end
+
+      private
+
+      attr_reader :dataset, :output_dir, :configuration
+
+      # api/v2/customers -> Api > V2 > Customers, requests in the leaf folder.
+      def folders
+        tree = { items: [], children: {} }
+
+        dataset.resources.each do |resource|
+          requests = resource.endpoints.select(&:curl_ready?).map { |endpoint| request_item(endpoint) }
+          next if requests.empty?
+
+          leaf = resource.segments.reduce(tree) do |node, segment|
+            node[:children][segment] ||= { items: [], children: {} }
+          end
+
+          leaf[:items].concat(requests)
+        end
+
+        render_folders(tree)
+      end
+
+      def render_folders(node)
+        node[:children].map do |segment, child|
+          { name: Support.titleize(segment), item: render_folders(child) + child[:items] }
+        end
+      end
+
+      def request_item(endpoint)
+        {
+          name: endpoint.name,
+          request: request_object(endpoint.primary_request_example, endpoint),
+          response: endpoint.responses.map { |response| response_object(response, endpoint) }
+        }
+      end
+
+      def request_object(example, endpoint)
+        {
+          method: example.method,
+          description: description(endpoint),
+          header: headers(example),
+          url: url_object(example),
+          body: body_object(example),
+          auth: request_auth(example)
+        }.compact
+      end
+
+      def description(endpoint)
+        lines = ["#{endpoint.method} #{endpoint.path}", "#{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
+
+      # The bearer credential lives on the collection; a request that carried
+      # it inherits, one that did not says so, so public endpoints replay
+      # exactly as their tests did.
+      def headers(example)
+        example.headers.filter_map do |key, value|
+          next if auth && key.to_s.casecmp?("Authorization")
+
+          { key: key.to_s, value: value.to_s }
+        end
+      end
+
+      def request_auth(example)
+        return nil unless auth
+        return nil if example.headers.any? { |key, _| key.to_s.casecmp?("Authorization") }
+
+        { type: "noauth" }
+      end
+
+      def url_object(example)
+        url = {
+          raw: "{{base_url}}#{Renderers::Payload.path_with_query(example)}",
+          host: ["{{base_url}}"],
+          path: example.path.split("/").reject(&:empty?),
+          query: Renderers::Payload.query_pairs(example).map { |key, value| { key: key, value: value.to_s } }
+        }
+
+        url.delete(:query) if url[:query].empty?
+        url
+      end
+
+      def body_object(example)
+        return nil unless example.body?
+
+        if Renderers::Payload.json?(example)
+          { mode: "raw", raw: Renderers::Payload.raw_body(example), options: { raw: { language: "json" } } }
+        elsif example.body.is_a?(Hash)
+          pairs = Renderers::Payload.form_pairs(example).map { |key, value| { key: key, value: value.to_s, type: "text" } }
+
+          { mode: "urlencoded", urlencoded: pairs }
+        else
+          { mode: "raw", raw: example.body.to_s }
+        end
+      end
+
+      def response_object(response, endpoint)
+        example = response.example
+        request = endpoint.request_examples.find { |candidate| candidate.response_status == response.status } ||
+                  endpoint.primary_request_example
+
+        {
+          name: example.title,
+          originalRequest: request_object(request, endpoint),
+          status: example.status_text,
+          code: response.status,
+          _postman_previewlanguage: example.content_type.to_s.include?("json") ? "json" : "text",
+          header: example.headers.map { |key, value| { key: key.to_s, value: value.to_s } },
+          body: response_body(example)
+        }
+      end
+
+      def response_body(example)
+        return "" unless example.body?
+        return example.body if example.body.is_a?(String)
+
+        JSON.pretty_generate(example.body)
+      end
+
+      # `base_url`, plus every `{{name}}` the sanitizer wrote into the
+      # documented examples, so the collection declares what it expects.
+      def variables
+        names = documented_examples.flat_map do |example|
+          [example.headers, example.body, example.query_params].flat_map do |value|
+            JSON.generate(value).scan(PLACEHOLDER).flatten
+          end
+        end
+
+        names |= (configuration.sanitized_headers.values + configuration.sanitized_body_keys.values)
+                 .flat_map { |value| value.to_s.scan(PLACEHOLDER).flatten }
+
+        [{ key: "base_url", value: configuration.base_url, type: "string" }] +
+          (names - ["base_url"]).uniq.sort.map { |name| { key: name, value: "", type: "string" } }
+      end
+
+      def auth
+        return @auth if defined?(@auth)
+
+        placeholder = documented_examples.filter_map do |example|
+          value = example.headers.find { |key, _| key.to_s.casecmp?("Authorization") }&.last
+          value.to_s[BEARER, 1]
+        end.first
+
+        @auth = placeholder && { type: "bearer", bearer: [{ key: "token", value: "{{#{placeholder}}}", type: "string" }] }
+      end
+
+      def documented_examples
+        @documented_examples ||= dataset.curl_ready_endpoints.flat_map(&:request_examples)
+      end
+    end
+
+    register("postman", Postman)
+  end
+end

data/lib/reqcord/exporters.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Reqcord
+  # Exporters register themselves here, so adding one means adding a file
+  # rather than editing the pipeline.
+  module Exporters
+    class << self
+      def register(name, exporter)
+        registry[name.to_s] = exporter
+      end
+
+      def fetch(name)
+        registry.fetch(name.to_s) do
+          raise ConfigurationError,
+                "unknown exporter #{name.inspect}, expected one of #{names.join(', ')}"
+        end
+      end
+
+      def registered?(name)
+        registry.key?(name.to_s)
+      end
+
+      def names
+        registry.keys.sort
+      end
+
+      def registry
+        @registry ||= {}
+      end
+    end
+  end
+end