reqcord 0.1.4 → 0.3.0

data/lib/reqcord/exporters/openapi.rb

@@ -0,0 +1,295 @@
+# 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 =
+          if Renderers::Payload.multipart?(example)
+            "multipart/form-data"
+          elsif Renderers::Payload.json?(example)
+            "application/json"
+          else
+            "application/x-www-form-urlencoded"
+          end
+
+        # A file part is shown by name in the example; the bytes are not data.
+        body = Renderers::Payload.display_body(example) { |file| FileValue.filename(file) }
+
+        {
+          required: true,
+          content: {
+            content_type => { schema: json_schema(endpoint.body_schema), 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
+        return { type: "string", format: "binary" } if types == ["file"]
+
+        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/exporters/postman.rb

@@ -135,7 +135,17 @@ module Reqcord
       def body_object(example)
         return nil unless example.body?
 
-        if Renderers::Payload.json?(example)
+        if Renderers::Payload.multipart?(example)
+          parts = Renderers::Payload.form_pairs(example).map do |key, value|
+            if FileValue.file?(value)
+              { key: key, type: "file", src: FileValue.filename(value) }
+            else
+              { key: key, value: value.to_s, type: "text" }
+            end
+          end
+
+          { mode: "formdata", formdata: parts }
+        elsif 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" } }

data/lib/reqcord/file_value.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Reqcord
+  # How an uploaded file travels through the dataset. The capture cannot keep
+  # the bytes (and the documentation must not), so a file becomes a small
+  # marker hash — `{"$file" => "avatar.png", "content_type" => "image/png"}` —
+  # that every renderer recognizes: `--form avatar=@avatar.png` in cURL, a
+  # `file` entry in Postman, `format: binary` in OpenAPI, type `file` in the
+  # parameter tables.
+  module FileValue
+    KEY = "$file"
+
+    module_function
+
+    def marker(filename, content_type = nil)
+      { KEY => filename.to_s, "content_type" => content_type.to_s.empty? ? nil : content_type.to_s }.compact
+    end
+
+    def file?(value)
+      value.is_a?(Hash) && value.key?(KEY)
+    end
+
+    def filename(value)
+      value[KEY].to_s
+    end
+
+    def content_type(value)
+      value["content_type"]
+    end
+
+    # "avatar.png (image/png)" — how a page shows the upload.
+    def describe(value)
+      type = content_type(value)
+
+      type ? "#{filename(value)} (#{type})" : filename(value)
+    end
+
+    # True when any value, at any depth, is a file marker.
+    def any?(value)
+      case value
+      when Hash then file?(value) || value.values.any? { |nested| any?(nested) }
+      when Array then value.any? { |item| any?(item) }
+      else false
+      end
+    end
+
+    # Returns a copy of `value` with every marker replaced by the block's
+    # result; used to render the body for a reader.
+    def map(value, &block)
+      case value
+      when Hash
+        return yield(value) if file?(value)
+
+        value.transform_values { |nested| map(nested, &block) }
+      when Array
+        value.map { |item| map(item, &block) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/reqcord/generator.rb

@@ -11,11 +11,13 @@ module Reqcord
   class Generator
     def self.call(
       resources: [],
-      version: nil
+      version: nil,
+      configuration: Reqcord.configuration
     )
       new(
         resources: resources,
-        version: version
+        version: version,
+        configuration: configuration
       ).call
     end
 
@@ -102,7 +104,7 @@ module Reqcord
         endpoints[[route, route.method]] = route.endpoint unless route.any_verb?
       end
 
-      exchanges.each do |raw_exchange|
+      ordered_exchanges(exchanges).each do |raw_exchange|
         sanitized =
           Sanitizers::Sanitizer.call(
             raw_exchange,
@@ -309,6 +311,18 @@ module Reqcord
       raise GenerationError, "could not match #{method} #{path} against the route table: #{e.message}"
     end
 
+    # Test suites run in random order, and "the first example captured" is
+    # what every page leads with. Ordering by where the test lives makes the
+    # output a function of the code, so regenerating never produces a diff
+    # by itself. Requests inside one test keep their execution order.
+    def ordered_exchanges(exchanges)
+      exchanges.each_with_index.sort_by do |exchange, index|
+        source = exchange["source"] || {}
+
+        [source["file"].to_s, source["line"].to_i, source["test"].to_s, index]
+      end.map(&:first)
+    end
+
     def attach_exchange(endpoint, exchange)
       request_data = exchange.fetch("request")
       response_data = exchange.fetch("response")

data/lib/reqcord/renderers/curl.rb

@@ -22,10 +22,14 @@ module Reqcord
         ]
 
         request.headers.each do |key, value|
+          next if key.to_s.casecmp?("Content-Type") && Payload.multipart?(request)
+
           parts << %(--header "#{key}: #{escape_header(value)}")
         end
 
-        parts << data_argument if request.body?
+        if request.body?
+          parts.concat(Payload.multipart?(request) ? form_arguments : [data_argument])
+        end
 
         parts.join(" \\\n  ")
       end
@@ -42,6 +46,23 @@ module Reqcord
         "--data '#{shell_single_quote(Payload.raw_body(request))}'"
       end
 
+      # One --form per part; a file is `@name`, relative to where the reader
+      # runs the command. curl sets the multipart Content-Type itself, so a
+      # captured one would only get in the way.
+      def form_arguments
+        Payload.form_pairs(request).map do |key, value|
+          part =
+            if FileValue.file?(value)
+              type = FileValue.content_type(value)
+              "#{key}=@#{FileValue.filename(value)}#{type ? ";type=#{type}" : ''}"
+            else
+              "#{key}=#{value}"
+            end
+
+          "--form '#{shell_single_quote(part)}'"
+        end
+      end
+
       def shell_single_quote(value)
         value.to_s.gsub("'", %q('"'"'))
       end

data/lib/reqcord/renderers/payload.rb

@@ -3,9 +3,9 @@
 module Reqcord
   module Renderers
     # The wire-level decisions every output format has to agree on: whether a
-    # request is JSON, how a nested query flattens, what the body looks like
-    # as text. cURL, Postman and any later exporter read these, never their
-    # own copy.
+    # request is JSON, a form or a multipart upload, how a nested query
+    # flattens, what the body looks like as text. cURL, Postman and any later
+    # exporter read these, never their own copy.
     module Payload
       module_function
 
@@ -16,18 +16,26 @@ module Reqcord
           end
       end
 
+      # A body with a file in it can only travel as multipart/form-data,
+      # whatever the captured content type says.
+      def multipart?(request)
+        request.content_type.to_s.include?("multipart/form-data") ||
+          FileValue.any?(request.body)
+      end
+
       # Rails bracket notation: { filter: { status: "a" }, ids: [1, 2] } becomes
-      # [["filter[status]", "a"], ["ids[]", 1], ["ids[]", 2]].
+      # [["filter[status]", "a"], ["ids[]", 1], ["ids[]", 2]]. A file marker is
+      # a leaf: the pair's value is the marker itself.
       def flatten_query(hash, prefix = nil)
         hash.flat_map do |key, value|
           current = prefix ? "#{prefix}[#{key}]" : key.to_s
 
           case value
           when Hash
-            flatten_query(value, current)
+            FileValue.file?(value) ? [[current, value]] : flatten_query(value, current)
           when Array
             value.flat_map do |item|
-              if item.is_a?(Hash)
+              if item.is_a?(Hash) && !FileValue.file?(item)
                 flatten_query(item, "#{current}[]")
               else
                 [["#{current}[]", item]]
@@ -54,7 +62,8 @@ module Reqcord
       end
 
       # The body as it goes on the wire: pretty JSON, a form string, or the
-      # raw text the test sent.
+      # raw text the test sent. Multipart has no single string; callers use
+      # form_pairs and render each part.
       def raw_body(request)
         if json?(request)
           JSON.pretty_generate(request.body)
@@ -64,6 +73,15 @@ module Reqcord
           request.body.to_s
         end
       end
+
+      # The body as a reader should see it: file markers replaced by their
+      # description ("avatar.png (image/png)"), or by whatever the block
+      # returns.
+      def display_body(request, &block)
+        block ||= FileValue.method(:describe)
+
+        FileValue.map(request.body, &block)
+      end
     end
   end
 end

data/lib/reqcord/route_collector.rb

@@ -216,7 +216,16 @@ module Reqcord
       prefixes = Array(prefix).map(&:to_s).reject(&:empty?)
       return true if prefixes.empty?
 
-      prefixes.any? { |candidate| path.start_with?(candidate) }
+      # Segment-wise: `/api` covers `/api`, `/api/v1/…` and `/api(/:id)`, not
+      # `/api-docs`.
+      prefixes.any? do |candidate|
+        candidate = candidate.chomp("/")
+        next true if candidate.empty?
+        next false unless path.start_with?(candidate)
+
+        rest = path.delete_prefix(candidate)
+        rest.empty? || rest.start_with?("/", "(")
+      end
     end
 
     # `RESOURCE=customers`, `RESOURCE=cart` (a singular resource is served by

data/lib/reqcord/schema.rb

@@ -110,7 +110,7 @@ module Reqcord
           )
 
           field.types |= [type_of(value)]
-          field.values |= [value] unless value.nil? || value.is_a?(Hash) || value.is_a?(Array)
+          field.values |= [example_value(value)] unless value.nil? || value.is_a?(Array) || (value.is_a?(Hash) && !FileValue.file?(value))
           field.present_count += 1
         end
       end
@@ -159,6 +159,9 @@ module Reqcord
     def flatten(value, prefix = nil, result = {})
       case value
       when Hash
+        # An upload is one field of type "file", not an object with two keys.
+        return result[prefix] = value if FileValue.file?(value) && prefix
+
         value.each { |key, nested| flatten(nested, prefix ? "#{prefix}.#{key}" : key.to_s, result) }
       when Array
         # An empty array still tells the reader the field is a list.
@@ -171,7 +174,14 @@ module Reqcord
       result
     end
 
+    # The file name stands for an upload in the Values column.
+    def example_value(value)
+      FileValue.file?(value) ? FileValue.filename(value) : value
+    end
+
     def type_of(value)
+      return "file" if FileValue.file?(value)
+
       case value
       when String then "string"
       when Integer then "integer"

data/lib/reqcord/version.rb

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