jekyll-openapi 0.1.0 → 0.2.0

data/lib/jekyll_openapi/reference.rb

@@ -0,0 +1,143 @@
+require "json"
+require_relative "json_pointer"
+
+module JekyllOpenAPI
+  ##
+  # Lazy, name-preserving stand-in for a JSON `$ref`.
+  #
+  # The Dereferencer replaces each `{"$ref" => ...}` node with a Reference
+  # rather than inlining its target. This keeps the reference *graph* — and the
+  # component *name* — intact, which buys three things the old inlining threw
+  # away:
+  #
+  #   * renderers/templates can link to a named schema instead of always
+  #     expanding it (see Schema#name);
+  #   * a schema reused N times resolves to one shared object, not N deep copies;
+  #   * recursion terminates, because targets are only followed on demand.
+  #
+  # For read access a Reference transparently delegates to its resolved target
+  # (`ref["type"]`, `ref.dig("schema", "pattern")`, iteration), so plain
+  # hash-walking templates keep working unchanged. `#reference?`, `#name` and
+  # `#ref` expose the pointer for code that wants to link rather than follow.
+  class Reference
+    # Shared per-dereference state: the linked root (for pointer resolution) and
+    # the logger. Populated by the Dereferencer once the whole tree is linked.
+    Context = Struct.new(:root, :logger)
+
+    attr_reader :ref, :overrides
+
+    # @param ref [String] the raw pointer, e.g. "#/components/schemas/Pet"
+    # @param context [Context] shared resolution state
+    # @param overrides [Hash] sibling summary/description overriding the target
+    def initialize(ref, context, overrides = {})
+      @ref = ref
+      @context = context
+      @overrides = overrides
+    end
+
+    def reference?
+      true
+    end
+
+    # True when the pointer is local to the current document (starts with "#").
+    def local?
+      @ref.is_a?(String) && @ref.start_with?("#")
+    end
+
+    # True when the pointer targets another file or URL (unsupported for now).
+    def external?
+      !local?
+    end
+
+    # Component name, e.g. "Pet" for "#/components/schemas/Pet"; nil when external.
+    def name
+      return nil unless local?
+      @name ||= JSONPointer.unescape(@ref.delete_prefix("#").split("/").last)
+    end
+
+    # The target node, lazily resolved and memoized, with `summary`/`description`
+    # overrides applied. Nested `$ref`s inside it are themselves References.
+    # Returns nil (warning once) for external or unresolvable pointers.
+    def resolve
+      return @resolved if @resolved_computed
+      @resolved_computed = true
+      @resolved = compute_resolution
+    end
+
+    # --- hash-like read delegation to the resolved target --------------------
+
+    def [](key)
+      return @ref if key == "$ref"
+      target = resolve
+      mapping?(target) ? target[key] : nil
+    end
+
+    def key?(key)
+      return true if key == "$ref"
+      target = resolve
+      mapping?(target) && target.key?(key)
+    end
+    alias_method :include?, :key?
+
+    def fetch(key, *default)
+      return self[key] if key?(key)
+      return yield(key) if block_given?
+      return default.first unless default.empty?
+      raise KeyError, "key not found: #{key.inspect}"
+    end
+
+    def dig(key, *rest)
+      value = self[key]
+      return value if rest.empty? || value.nil?
+      value.respond_to?(:dig) ? value.dig(*rest) : nil
+    end
+
+    def each(&block)
+      target = resolve
+      target.each(&block) if target.respond_to?(:each)
+    end
+    alias_method :each_pair, :each
+
+    # Liquid indexes us like the hash we stand for (it calls #to_liquid on every
+    # value and does not patch arbitrary objects), so hand it back ourselves.
+    def to_liquid
+      self
+    end
+
+    # A Reference merges like the hash it stands for (used by Parameters.merge).
+    def to_hash
+      target = resolve
+      target.is_a?(Hash) ? target : { "$ref" => @ref }
+    end
+    alias_method :to_h, :to_hash
+
+    # Serialize back to a $ref node. Finite by construction (it never expands the
+    # target), so `oapi_dereference | jsonify` stays bounded even for recursive
+    # schemas, and round-trips to a valid OpenAPI reference.
+    def to_json(*args)
+      { "$ref" => @ref }.to_json(*args)
+    end
+
+    private
+
+    def mapping?(node)
+      node.is_a?(Hash) || node.is_a?(Reference)
+    end
+
+    def compute_resolution
+      unless local?
+        @context.logger.warn("external or invalid $ref left unresolved: #{@ref.inspect}")
+        return nil
+      end
+      target = JSONPointer.resolve(@context.root, @ref.delete_prefix("#"))
+      if target.nil?
+        @context.logger.warn("unresolvable $ref: #{@ref}")
+        return nil
+      end
+      # Apply OpenAPI 3.1 sibling overrides without disturbing the shared target
+      # (so diamond reuse keeps object identity when there are no overrides).
+      return target unless target.is_a?(Hash) && !@overrides.empty?
+      target.merge(@overrides)
+    end
+  end
+end

data/lib/jekyll_openapi/schema.rb

@@ -0,0 +1,189 @@
+require_relative "reference"
+require_relative "json_pointer"
+
+module JekyllOpenAPI
+  ##
+  # Normalized, ref-aware view over a JSON-Schema node, shared by every schema
+  # renderer.
+  #
+  # It centralises the two things that used to be copy-pasted (and drift) across
+  # the TypeScript and XML renderers: the type *inference* that fills in an
+  # omitted `type`, and the `$ref` *following* with cycle detection. A new
+  # renderer (JSON example, HTML, …) implements formatting only — it never walks
+  # raw hashes or re-infers types.
+  #
+  # Schemas are immutable and carry the set of `$ref` pointers already followed
+  # on the current path (`seen`), so following a self-referential schema stops
+  # instead of looping, while genuine reuse (the same schema in two branches)
+  # is never mistaken for a cycle.
+  class Schema
+    # Sentinel returned by #follow when a `$ref` points back onto the path.
+    CYCLE = :cycle
+
+    def self.wrap(node, seen = [])
+      node.is_a?(Schema) ? node : new(node, seen)
+    end
+
+    attr_reader :seen
+
+    def initialize(node, seen = [])
+      @node = node
+      @seen = seen
+    end
+
+    def raw
+      @node
+    end
+
+    # Whether this wraps something readable as a schema object.
+    def mapping?
+      @node.is_a?(Hash) || @node.is_a?(Reference)
+    end
+
+    # A $ref node — either a linked {Reference} (produced by the Dereferencer)
+    # or a raw, un-dereferenced `{"$ref" => "..."}` hash. Link-mode rendering
+    # only needs the pointer string, so it works on either form (see #ref/#name);
+    # *following* a ref to inline its target still requires a linked Reference
+    # (a raw ref carries no root to resolve against — see #follow).
+    def reference?
+      @node.is_a?(Reference) || raw_reference?
+    end
+
+    # A plain `{"$ref" => "..."}` hash that never went through the Dereferencer.
+    def raw_reference?
+      @node.is_a?(Hash) && @node["$ref"].is_a?(String)
+    end
+
+    # The raw pointer string, e.g. "#/components/schemas/Pet"; nil when not a ref.
+    def ref
+      return @node.ref if @node.is_a?(Reference)
+      return @node["$ref"] if raw_reference?
+      nil
+    end
+
+    # Component name of a local ref, e.g. "Pet" for "#/components/schemas/Pet";
+    # nil for external refs or non-refs. Derived from the pointer alone, so it
+    # needs no dereferencing.
+    def name
+      pointer = ref
+      return nil unless pointer.is_a?(String) && pointer.start_with?("#")
+      JSONPointer.unescape(pointer.delete_prefix("#").split("/").last)
+    end
+
+    # A local $ref to a named component — the kind an HTML renderer links to
+    # rather than inlines. External refs (no local name) return false.
+    def named_reference?
+      reference? && !name.nil?
+    end
+
+    # The use-site description sitting beside a $ref (a 3.1 sibling override),
+    # if any. Lets a renderer annotate a link without expanding its target.
+    def override_description
+      return @node.overrides["description"] if @node.is_a?(Reference)
+      return @node["description"] if raw_reference?
+      nil
+    end
+
+    # Follow a `$ref` one hop.
+    # @return [Schema] the target when resolvable,
+    #   CYCLE when the ref is already on the current path,
+    #   nil when external, unresolvable, or a raw (never-dereferenced) ref that
+    #   carries no root to resolve against (a warning is emitted by Reference).
+    def follow
+      return self unless reference?
+      pointer = ref
+      return CYCLE if @seen.include?(pointer)
+      target = @node.is_a?(Reference) ? @node.resolve : nil
+      target.nil? ? nil : Schema.new(target, @seen + [pointer])
+    end
+
+    # Raw read, delegating through a Reference transparently.
+    def [](key)
+      mapping? ? @node[key] : nil
+    end
+
+    def dig(*keys)
+      mapping? ? @node.dig(*keys) : nil
+    end
+
+    # --- composition ---------------------------------------------------------
+
+    # @return [Array(String, Array<Schema>), nil] e.g. ["oneOf", [Schema, ...]]
+    def composition
+      %w[oneOf anyOf allOf].each do |keyword|
+        members = self[keyword]
+        return [keyword, members.map { |m| child(m) }] if members.is_a?(Array)
+      end
+      nil
+    end
+
+    # --- type ----------------------------------------------------------------
+
+    def declared_type
+      self["type"]
+    end
+
+    def type_union?
+      declared_type.is_a?(Array)
+    end
+
+    # Single inferred type, mirroring what most tooling assumes when `type` is
+    # omitted. Returns nil for a type union (see #type_union?) or the unknown.
+    def type
+      declared = declared_type
+      return declared if declared.is_a?(String)
+      return nil if declared.is_a?(Array)
+      return "object" if self["properties"] || self["additionalProperties"]
+      return "array" if self["items"]
+      return "string" if self["enum"]
+      nil
+    end
+
+    # A copy of this schema with `type` pinned to one member of a type union.
+    def with_type(single)
+      node = @node.is_a?(Hash) ? @node.merge("type" => single) : @node
+      Schema.new(node, @seen)
+    end
+
+    # --- object --------------------------------------------------------------
+
+    def properties
+      (self["properties"] || {}).map { |key, node| [key, child(node)] }
+    end
+
+    def required?(key)
+      Array(self["required"]).include?(key)
+    end
+
+    # @return [Schema, nil] the additionalProperties schema, only when it is a
+    #   schema object (the boolean `true`/`false` forms carry no shape to render)
+    def additional_properties
+      value = self["additionalProperties"]
+      value.is_a?(Hash) || value.is_a?(Reference) ? child(value) : nil
+    end
+
+    # --- array ---------------------------------------------------------------
+
+    def items
+      child(self["items"])
+    end
+
+    # --- leaf metadata -------------------------------------------------------
+
+    def enum = self["enum"]
+    def format = self["format"]
+    def pattern = self["pattern"]
+    def summary = self["summary"]
+    def description = self["description"]
+    def example = self["example"]
+    def examples = self["examples"]
+    def xml = self["xml"] || {}
+
+    private
+
+    # Descending into a member keeps the current cycle path (no ref followed).
+    def child(node)
+      Schema.wrap(node, @seen)
+    end
+  end
+end

data/lib/jekyll_openapi/schema_renderer/html.rb

@@ -0,0 +1,186 @@
+require "cgi"
+require_relative "../schema"
+
+module JekyllOpenAPI
+  module SchemaRenderer
+    ##
+    # Renders a JSON-Schema as semantic, linkable HTML.
+    #
+    # Unlike the TypeScript/XML renderers — which always follow `$ref`s and
+    # inline everything — this renderer works in *link mode*: a reference to a
+    # named component schema becomes an anchor to that schema's definition
+    # (`#schema-<name>`) instead of being expanded. Anonymous inline schemas are
+    # rendered structurally. That keeps operation bodies compact, cross-links
+    # reused types, and makes recursion terminate for free (a link is never
+    # followed).
+    #
+    # Markup is semantic and class-annotated (`<dl>`/`<ul>`/`<div>`, never
+    # tables); all styling is left to the consumer. Every class is `oapi-`
+    # prefixed. Emitted text is HTML-escaped.
+    #
+    # Descriptions are plain-escaped by default. Pass a `markdown:` callable
+    # (`text -> html`) to render them as markdown instead — the core library has
+    # no markdown engine of its own, so the caller supplies one (the Jekyll
+    # filter wires in the site's converter; see Filters#oapi_html_schema).
+    class HTML
+      # Fragment prefix for a named schema, e.g. "schema-Pet". A Models section
+      # anchors each definition with the matching id (see oapi_schema_anchor).
+      ANCHOR_PREFIX = "schema-"
+
+      def self.anchor(name)
+        "#{ANCHOR_PREFIX}#{name}"
+      end
+
+      # @param markdown [#call, nil] a `text -> html` converter for descriptions;
+      #   when nil, descriptions are HTML-escaped plain text
+      def initialize(logger: JekyllOpenAPI.logger, markdown: nil)
+        @logger = logger
+        @markdown = markdown
+      end
+
+      def self.render(schema, logger: JekyllOpenAPI.logger, markdown: nil)
+        new(logger: logger, markdown: markdown).render(schema)
+      end
+
+      # @param input [Hash, Reference, Schema] a JSON-Schema
+      # @return [String] HTML
+      def render(input)
+        schema = Schema.wrap(input)
+
+        if schema.named_reference?
+          # Link, don't follow. Any use-site (sibling) description still shows.
+          return annotate(link(schema), schema.override_description)
+        end
+        if schema.reference?
+          # External/unnamed ref: surface the pointer, don't fake a type.
+          return ref_code(schema)
+        end
+        unless schema.mapping?
+          @logger.warn("not a valid schema object: #{schema.raw.inspect}")
+          return ""
+        end
+
+        html = base(schema)
+        return "" if html.nil?
+        annotate(html, schema.description)
+      end
+
+      private
+
+      def base(schema)
+        return composition(schema) if schema.composition
+        return type_union(schema) if schema.type_union?
+
+        case schema.type
+        when "object" then object(schema)
+        when "array" then array(schema)
+        when "string" then string(schema)
+        when "null" then span("oapi-type", "null")
+        when nil
+          @logger.warn("not a valid schema object: #{schema.raw.inspect}")
+          nil
+        else
+          primitive(schema)
+        end
+      end
+
+      def object(schema)
+        rows = schema.properties.map do |key, property|
+          required = schema.required?(key)
+          name = "#{span("oapi-prop-name", key)}#{required ? required_marker : ""}"
+          <<~ROW.chomp
+            <div class="oapi-prop#{required ? " oapi-prop-required" : ""}">
+            <dt>#{name}</dt>
+            <dd>#{render(property)}</dd>
+            </div>
+          ROW
+        end
+        rows << additional_row(schema)
+        "<dl class=\"oapi-object\">#{rows.compact.join}</dl>"
+      end
+
+      # additionalProperties: a schema (typed map), `true` (open) or absent.
+      def additional_row(schema)
+        value =
+          if (additional = schema.additional_properties)
+            render(additional)
+          elsif schema["additionalProperties"] == true
+            span("oapi-type", "any")
+          end
+        return nil unless value
+        <<~ROW.chomp
+          <div class="oapi-prop oapi-prop-additional">
+          <dt>#{span("oapi-additional-key", "additional properties")}</dt>
+          <dd>#{value}</dd>
+          </div>
+        ROW
+      end
+
+      def array(schema)
+        "<div class=\"oapi-array\">#{span("oapi-array-label", "array of")} #{render(schema.items)}</div>"
+      end
+
+      def string(schema)
+        if schema.enum
+          values = schema.enum.map { |value| "<li>#{code("oapi-enum-value", value)}</li>" }.join
+          "<ul class=\"oapi-enum\">#{values}</ul>"
+        else
+          primitive(schema, "string")
+        end
+      end
+
+      def primitive(schema, type = schema.type)
+        html = span("oapi-type", type)
+        html += " #{span("oapi-format", "(#{schema.format})")}" if schema.format
+        html += " #{code("oapi-pattern", "/#{schema.pattern}/")}" if schema.pattern
+        html
+      end
+
+      def composition(schema)
+        keyword, members = schema.composition
+        items = members.map { |member| "<li>#{render(member)}</li>" }.join
+        "<ul class=\"oapi-union\" data-kind=\"#{keyword}\">#{items}</ul>"
+      end
+
+      # OpenAPI 3.1 type array, e.g. ["string", "null"]
+      def type_union(schema)
+        types = schema.declared_type
+        parts = (types - ["null"]).map { |type| base(schema.with_type(type)) }
+        parts << span("oapi-nullable", "null") if types.include?("null")
+        parts.join(" #{span("oapi-or", "|")} ")
+      end
+
+      def link(schema)
+        name = schema.name
+        "<a class=\"oapi-ref\" href=\"##{ANCHOR_PREFIX}#{CGI.escapeHTML(name)}\">#{escape(name)}</a>"
+      end
+
+      def ref_code(schema)
+        code("oapi-ref-external", schema.ref)
+      end
+
+      def annotate(html, description)
+        return html if description.nil? || description.empty?
+        # A markdown converter returns trusted HTML; without one, escape the text.
+        body = @markdown ? @markdown.call(description) : escape(description)
+        "#{html}<div class=\"oapi-desc\">#{body}</div>"
+      end
+
+      def required_marker
+        "<span class=\"oapi-required\">required</span>"
+      end
+
+      def span(cls, text)
+        "<span class=\"#{cls}\">#{escape(text)}</span>"
+      end
+
+      def code(cls, text)
+        "<code class=\"#{cls}\">#{escape(text)}</code>"
+      end
+
+      def escape(text)
+        CGI.escapeHTML(text.to_s)
+      end
+    end
+  end
+end

data/lib/jekyll_openapi/schema_renderer/typescript.rb

@@ -1,7 +1,11 @@
+require_relative "../schema"
+
 module JekyllOpenAPI
   module SchemaRenderer
     ##
     # Renders a JSON-Schema as a simplified TypeScript-like textual representation.
+    # Traversal, type inference and `$ref` following live in {Schema}; this class
+    # only decides how each shape prints.
     # @see https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00
     class TypeScript
       def initialize(logger: JekyllOpenAPI.logger)
@@ -12,94 +16,100 @@ module JekyllOpenAPI
         new(logger: logger).render(schema)
       end
 
-      # @param input [Hash] a JSON-Schema
+      # @param input [Hash, Reference, Schema] a JSON-Schema
       # @param prefix [String] current indentation
       # @return [String]
       def render(input, prefix = "")
-        unless input.is_a?(Hash)
-          @logger.warn("not a valid schema object: #{input.inspect}")
+        schema = Schema.wrap(input)
+
+        if schema.reference?
+          followed = schema.follow
+          # A cycle prints the schema's name (e.g. "Node") instead of looping.
+          return schema.name.to_s if followed == Schema::CYCLE
+          return "" if followed.nil?
+          return render(followed, prefix)
+        end
+
+        unless schema.mapping?
+          @logger.warn("not a valid schema object: #{schema.raw.inspect}")
           return ""
         end
-        str = base(input, prefix)
+
+        str = base(schema, prefix)
         return "" if str.nil?
-        annotate(str, input)
+        annotate(str, schema)
       end
 
       private
 
-      def base(input, prefix)
-        return union(input["oneOf"], prefix, " | ") if input["oneOf"]
-        return union(input["anyOf"], prefix, " | ") if input["anyOf"]
-        return union(input["allOf"], prefix, " & ") if input["allOf"]
-
-        type = input["type"]
-        return type_union(input, prefix) if type.is_a?(Array)
-        # infer the type when omitted, as most tooling does
-        type ||= "object" if input["properties"] || input["additionalProperties"]
-        type ||= "array" if input["items"]
-        type ||= "string" if input["enum"]
+      def base(schema, prefix)
+        if (composition = schema.composition)
+          keyword, members = composition
+          separator = keyword == "allOf" ? " & " : " | "
+          return members.map { |member| render(member, prefix) }.join(separator)
+        end
+        return type_union(schema, prefix) if schema.type_union?
 
-        case type
-        when "object" then object(input, prefix)
-        when "array" then "[ #{render(input["items"], prefix)} ]"
-        when "string" then string(input)
+        case schema.type
+        when "object" then object(schema, prefix)
+        when "array" then "[ #{render(schema.items, prefix)} ]"
+        when "string" then string(schema)
         when "null" then "null"
         when nil
-          @logger.warn("not a valid schema object: #{input.inspect}")
+          @logger.warn("not a valid schema object: #{schema.raw.inspect}")
           nil
         else
-          primitive(input, type)
+          primitive(schema)
         end
       end
 
-      def union(schemas, prefix, separator)
-        schemas.map { |schema| render(schema, prefix) }.join(separator)
-      end
-
       # OpenAPI 3.1 / JSON-Schema type arrays, e.g. type: [string, "null"]
-      def type_union(input, prefix)
-        types = input["type"]
-        rendered = (types - ["null"]).map { |t| base(input.merge("type" => t), prefix) }
+      def type_union(schema, prefix)
+        types = schema.declared_type
+        rendered = (types - ["null"]).map { |t| base(schema.with_type(t), prefix) }
         rendered.push("null") if types.include?("null")
         rendered.join(" | ")
       end
 
-      def object(input, prefix)
+      def object(schema, prefix)
         str = "{"
-        (input["properties"] || {}).each do |key, schema|
-          required = Array(input["required"]).include?(key)
-          str += "\n#{prefix}  #{key}#{required ? "" : "?"}: #{render(schema, prefix + "  ")}"
+        schema.properties.each do |key, property|
+          optional = schema.required?(key) ? "" : "?"
+          str += "\n#{prefix}  #{key}#{optional}: #{render(property, prefix + "  ")}"
         end
-        props = input["additionalProperties"]
-        if props.is_a?(Hash)
-          str += "\n#{prefix}  [#{props["type"]}]?: #{render(props, prefix + "  ")}"
+        if (additional = schema.additional_properties)
+          str += "\n#{prefix}  [#{additional.type}]?: #{render(additional, prefix + "  ")}"
+        elsif schema["additionalProperties"] == true
+          # open map with an unconstrained value type; `false` is the closed
+          # default and needs no annotation
+          str += "\n#{prefix}  [string]?: any"
         end
         "#{str}\n#{prefix}}"
       end
 
-      def string(input)
-        if input["enum"]
-          input["enum"].map { |v| "\"#{v}\"" }.join("|")
-        elsif input["format"] == "binary"
+      def string(schema)
+        if schema.enum
+          schema.enum.map { |value| "\"#{value}\"" }.join("|")
+        elsif schema.format == "binary"
           "Buffer"
         else
           "\"string\""
         end
       end
 
-      def primitive(input, type)
-        str = type.to_s
-        str += " (#{input["format"]})" if input["format"]
+      def primitive(schema)
+        str = schema.type.to_s
+        str += " (#{schema.format})" if schema.format
         str
       end
 
-      def annotate(str, input)
-        str = "#{str} // /#{input["pattern"]}/" if input["pattern"]
-        if input["summary"]
-          str = "#{str} //#{input["summary"]}"
-        elsif input["description"]
+      def annotate(str, schema)
+        str = "#{str} // /#{schema.pattern}/" if schema.pattern
+        if schema.summary
+          str = "#{str} //#{schema.summary}"
+        elsif schema.description
           padding = "".rjust(str.length, " ")
-          str = "#{str} //#{input["description"].split("\n").join("\n#{padding} //")}"
+          str = "#{str} //#{schema.description.split("\n").join("\n#{padding} //")}"
         end
         str
       end