jekyll-openapi 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 989a754db0f9b16a6ddcdc250248e360400b0f7e1cee52c29879f666611036e9
-  data.tar.gz: 1421051366aff8e848f3c451b966a128132ae001e26698e5ea22a99eb9b9afb1
+  metadata.gz: 115a158c4677920431b493e1d8941d8bc84f7ac71f0d9813f386ed9a1391878d
+  data.tar.gz: 2444e2822f9181d34c4ade929b0903861d43ea6b9a9376db09baef3abe779906
 SHA512:
-  metadata.gz: d1a17b202abcf9defa2200d5c99df7dc8f21f563e0b8166bd5cadc605d91f48a4c56ba18ec37af4eb15f1c3fbf49022bb7e209281a457f7c172bc06b903c9905
-  data.tar.gz: 70aa7e5ad448fc234a1d4c13e66c5cf0cf5ad06d7a8a236e28b90279578b5f36ef74ea316c9f7f05c811aeb4ac363cf0aba91050b4623b1bc570da124b83ddc6
+  metadata.gz: 800e3dd82c5c47f0b5b1e31319199ffc5045eb72ebc5285062ab2ecb0e831bcb56a842b7fd168bd239b9b4ac194056c1a2d059650361f6cf484857ac3d0704de
+  data.tar.gz: 677f5f4053e77ec018823e08e24cf89e3a2b44c70ea5267368eee22e83195407872487f134646743a2dcfca9bc78d284501b3140e12c771598e0bfa4bca0e1fc

data/README.md

@@ -107,17 +107,28 @@ schemas — start from the complete examples and restyle them:
 Registered automatically in Jekyll. (In a plain Liquid setup you register them
 yourself — see [examples/ruby/README.md](examples/ruby/README.md#liquid-filters-outside-jekyll).)
 
-| filter                  | input → output |
-|-------------------------|----------------|
-| `oapi_dereference`      | document → document with local `$ref`s resolved |
-| `oapi_tags`             | document → tag list |
-| `oapi_operations`       | document (+ optional tag argument) → operation list |
-| `oapi_parameters`       | parameter list → grouped by location |
-| `oapi_merge_parameters` | path params, operation params → merged list |
-| `oapi_schema`           | JSON-Schema → TypeScript-like string |
-| `oapi_xml_schema`       | JSON-Schema → simplified XML string |
-
-The two schema filters turn a JSON-Schema into readable text, e.g.
+| filter                   | input → output |
+|--------------------------|----------------|
+| `oapi_dereference`       | document → document with local `$ref`s made navigable (lazy, name-preserving). Optional — every filter below dereferences internally; call it only if you also hand-walk the raw hash. Idempotent. |
+| `oapi_tags`              | document → tag list |
+| `oapi_operations`        | document (+ optional tag argument) → operation list |
+| `oapi_parameters`        | parameter list → grouped by location |
+| `oapi_merge_parameters`  | path params, operation params → merged list |
+| `oapi_examples`          | parameter or media-type object → normalized `{name, value, summary, description}` list, unifying `examples`/`example`/schema-level examples |
+| `oapi_headers`           | response object → normalized `{name, description, required, deprecated, schema}` list (`$ref`'d headers resolved) |
+| `oapi_schemas`           | document → named component-schema map (for a Models section) |
+| `oapi_security_schemes`  | document → named security-scheme map |
+| `oapi_servers`           | document → server list |
+| `oapi_schema`            | JSON-Schema → TypeScript-like string |
+| `oapi_xml_schema`        | JSON-Schema → simplified XML string |
+| `oapi_html_schema`       | JSON-Schema → semantic HTML; named component refs become links. Works on dereferenced *or* raw `{"$ref": …}` schemas (link mode needs only the pointer). |
+| `oapi_schema_anchor`     | schema name → `schema-<name>` anchor id |
+| `oapi_operation_anchor`  | operation entry (or operationId) → fragment id; falls back to method+path when operationId is absent |
+| `oapi_tag_anchor`        | tag object (or name) → fragment id |
+| `oapi_representation`    | media-type string → `"xml"`/`"json"`/`"text"`/`"binary"` (robust to `text/xml`, `*+xml`, `; charset=…`) |
+| `oapi_is_xml`            | media-type string → boolean (XML-family) |
+
+The text schema filters turn a JSON-Schema into readable text, e.g.
 `{{ content.schema | oapi_schema }}` produces:
 
 ```typescript
@@ -127,15 +138,26 @@ The two schema filters turn a JSON-Schema into readable text, e.g.
 }
 ```
 
-See [examples/jekyll/_includes/oapi/schema.html](examples/jekyll/_includes/oapi/schema.html)
-for choosing the renderer by content type.
+`oapi_html_schema` instead emits semantic, class-annotated HTML (`<dl>`/`<ul>`,
+never tables) in which a `$ref` to a named component schema renders as a link to
+`#schema-<name>` rather than being inlined — so operation bodies stay compact,
+reused types are cross-linked, and recursive schemas terminate. Descriptions are
+rendered as markdown when run inside Jekyll (it reuses the site's configured
+converter) and as escaped plain text otherwise. Pair it with
+`oapi_schemas` + `oapi_schema_anchor` to emit a matching "Models" section; see
+[examples/jekyll/_includes/oapi/models.html](examples/jekyll/_includes/oapi/models.html)
+and [schema.html](examples/jekyll/_includes/oapi/schema.html) (which picks a
+renderer by content type), styled by
+[_sass/oapi-schema.scss](examples/jekyll/_sass/oapi-schema.scss).
 
 ## Error handling
 
 The library never raises on malformed input: it warns through
 `JekyllOpenAPI.logger` (in Jekyll, routed to Jekyll's own logger) and degrades
-gracefully — unresolvable, external, and circular `$ref`s are left in place;
-invalid schemas render as `""`. Your build never breaks on a bad spec.
+gracefully — unresolvable and external `$ref`s are left in place and warn only
+when followed; recursive schemas terminate (rendered as a link, or their name in
+the text renderers); invalid schemas render as `""`. Your build never breaks on
+a bad spec.
 
 ## Compliance notes
 

data/lib/jekyll_openapi/anchors.rb

@@ -0,0 +1,45 @@
+require_relative "reference"
+
+module JekyllOpenAPI
+  ##
+  # Stable, deterministic fragment ids for operations and tags — the counterpart
+  # to SchemaRenderer::HTML.anchor for the parts of a reference page the schema
+  # renderer does not own.
+  #
+  # `operationId` is *optional* in OpenAPI, so a template that anchors on it
+  # alone emits `id=""` (and collisions) the day an operation omits it; here the
+  # method+path is the fallback. The slug matches Jekyll's default `slugify`
+  # (downcase, non-alphanumeric runs to single hyphens, trimmed) so these are
+  # drop-in replacements for a hand-rolled `| slugify` and keep existing anchor
+  # URLs stable.
+  module Anchors
+    # @param op [Hash, String] an operation entry (from Document#operations) or
+    #   a bare operationId
+    def self.operation(op)
+      id =
+        if op.is_a?(Hash) || op.is_a?(Reference)
+          dig(op, "operation", "operationId") || dig(op, "operationId") ||
+            "#{op["method"]} #{op["path"]}"
+        else
+          op
+        end
+      slug(id)
+    end
+
+    # @param tag [Hash, String] a tag object (from Document#tags) or a bare name
+    def self.tag(tag)
+      name = (tag.is_a?(Hash) || tag.is_a?(Reference)) ? tag["name"] : tag
+      slug(name)
+    end
+
+    # Jekyll-`slugify`-compatible (default mode) slug.
+    def self.slug(text)
+      text.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+    end
+
+    def self.dig(object, *keys)
+      object.respond_to?(:dig) ? object.dig(*keys) : nil
+    end
+    private_class_method :dig
+  end
+end

data/lib/jekyll_openapi/content_type.rb

@@ -0,0 +1,26 @@
+module JekyllOpenAPI
+  ##
+  # Classifies a media-type string so templates pick a schema representation
+  # without brittle `== "application/xml"` comparisons that miss `text/xml`,
+  # `application/*+xml`, or a trailing `; charset=…` parameter.
+  module ContentType
+    # @return [String] one of "xml", "json", "text", "binary"
+    def self.representation(content_type)
+      ct = normalize(content_type)
+      return "xml" if ct == "application/xml" || ct == "text/xml" || ct.end_with?("+xml")
+      return "json" if ct == "application/json" || ct.end_with?("+json")
+      return "text" if ct.start_with?("text/")
+      "binary"
+    end
+
+    def self.xml?(content_type)
+      representation(content_type) == "xml"
+    end
+
+    # Strip any `; charset=…`/parameters and normalize case/whitespace.
+    def self.normalize(content_type)
+      content_type.to_s.split(";").first.to_s.strip.downcase
+    end
+    private_class_method :normalize
+  end
+end

data/lib/jekyll_openapi/dereferencer.rb

@@ -1,10 +1,15 @@
 require_relative "json_pointer"
+require_relative "reference"
 
 module JekyllOpenAPI
   ##
-  # Recursively resolves local `$ref` pointers in an OpenAPI document.
-  # External references (other files, URLs) are left in place with a warning.
-  # Circular references are detected and left in place instead of recursing forever.
+  # Walks an OpenAPI document once and replaces every local `$ref` node with a
+  # lazy {Reference} instead of inlining its target. The reference graph and
+  # component names are preserved; targets are resolved on demand (see
+  # Reference), which keeps recursion finite and reused schemas shared.
+  #
+  # External references (other files, URLs) and unresolvable pointers surface a
+  # warning when they are first followed, not while linking.
   class Dereferencer
     def initialize(root, logger: JekyllOpenAPI.logger)
       @root = root
@@ -15,49 +20,30 @@ module JekyllOpenAPI
       new(root, logger: logger).dereference
     end
 
-    # @return a deep copy of the document with every local $ref replaced by its target
-    def dereference(node = @root, stack = [])
+    # @return a deep copy of the document with every `$ref` replaced by a
+    #   Reference that resolves lazily against the copy.
+    def dereference
+      context = Reference::Context.new(nil, @logger)
+      context.root = link(@root, context)
+      context.root
+    end
+
+    private
+
+    def link(node, context)
       case node
       when Hash
         if node.key?("$ref")
-          resolve(node, stack)
+          # summary/description may sit beside $ref and override the target (3.1)
+          Reference.new(node["$ref"], context, node.slice("summary", "description"))
         else
-          node.transform_values { |value| dereference(value, stack) }
+          node.transform_values { |value| link(value, context) }
         end
       when Array
-        node.map { |value| dereference(value, stack) }
+        node.map { |value| link(value, context) }
       else
         node
       end
     end
-
-    private
-
-    def resolve(node, stack)
-      ref = node["$ref"]
-      unless ref.is_a?(String) && ref.start_with?("#")
-        @logger.warn("external or invalid $ref left unresolved: #{ref.inspect}")
-        return node
-      end
-      if stack.include?(ref)
-        @logger.warn("circular $ref left unresolved: #{ref}")
-        return node
-      end
-
-      target = JSONPointer.resolve(@root, ref.delete_prefix("#"))
-      if target.nil?
-        @logger.warn("unresolvable $ref: #{ref}")
-        return node
-      end
-
-      resolved = dereference(target, stack + [ref])
-      # OpenAPI 3.1 allows summary/description as siblings of $ref, overriding the target's
-      overrides = node.slice("summary", "description")
-      if resolved.is_a?(Hash) && !overrides.empty?
-        resolved.merge(overrides)
-      else
-        resolved
-      end
-    end
   end
 end

data/lib/jekyll_openapi/document.rb

@@ -9,7 +9,10 @@ module JekyllOpenAPI
   #
   # Absorbs the spec-aware traversal that would otherwise live in templates:
   # enumerating operations (including `x-` extension methods), filtering by tag,
-  # and merging path-level with operation-level parameters.
+  # merging path-level with operation-level parameters, and surfacing the
+  # component collections (schemas, security schemes, servers) that a reference
+  # page needs. `$ref`s stay navigable but keep their names (see Reference), so
+  # templates can link named schemas instead of inlining them.
   class Document
     HTTP_METHODS = %w[get put post delete options head patch trace].freeze
     PATH_ITEM_FIELDS = %w[summary description servers parameters $ref].freeze
@@ -32,7 +35,8 @@ module JekyllOpenAPI
       new(data, logger: logger)
     end
 
-    # @return [Hash] the document with all local $refs resolved (memoized)
+    # @return [Hash] a copy of the document in which every local `$ref` is a lazy
+    #   Reference (navigable, name-preserving, resolved on demand); memoized
     def dereferenced
       @dereferenced ||= Dereferencer.new(@data, logger: @logger).dereference
     end
@@ -49,6 +53,36 @@ module JekyllOpenAPI
       dereferenced["paths"] || {}
     end
 
+    # Declared servers (empty when the document omits them).
+    def servers
+      dereferenced["servers"] || []
+    end
+
+    # Top-level security requirements applied to every operation by default.
+    def security
+      dereferenced["security"] || []
+    end
+
+    # The whole `components` object. Prefer the named helpers below.
+    def components
+      dereferenced["components"] || {}
+    end
+
+    ##
+    # Named schema map, e.g. for a "Models" reference section. Values keep their
+    # nested `$ref`s as References, so a template can render each schema's body
+    # and cross-link by name (see Schema#name) rather than inline everything.
+    # @return [Hash{String => Object}]
+    def schemas
+      components["schemas"] || {}
+    end
+
+    # Named security scheme map (apiKey/http/oauth2/openIdConnect definitions).
+    # @return [Hash{String => Object}]
+    def security_schemes
+      components["securitySchemes"] || {}
+    end
+
     ##
     # Flat list of every operation in the document, in path order.
     # `x-`-prefixed extension methods (e.g. webDAV verbs) are included,
@@ -78,11 +112,22 @@ module JekyllOpenAPI
 
     def build_operations
       paths.flat_map do |path, path_item|
+        # A path item (and, less regularly, an operation) may itself be a $ref;
+        # follow it so referenced operations are not silently dropped.
+        path_item = follow(path_item)
         next [] unless path_item.is_a?(Hash)
         path_item.filter_map do |key, operation|
           next if PATH_ITEM_FIELDS.include?(key)
           next unless HTTP_METHODS.include?(key) || key.start_with?("x-")
+          operation = follow(operation)
           next unless operation.is_a?(Hash)
+          # `x-` is OpenAPI's extension mechanism, not a method namespace: a
+          # path-item extension is only an operation when it actually carries an
+          # Operation Object. `operationId`/`responses` mark one; vendor metadata
+          # (x-internal, x-codegen, …) has neither and must not become a phantom
+          # method. Standard HTTP verbs are always operations.
+          next if key.start_with?("x-") &&
+            !(operation.key?("operationId") || operation.key?("responses"))
 
           params = Parameters.merge(path_item["parameters"], operation["parameters"])
           {
@@ -96,5 +141,10 @@ module JekyllOpenAPI
         end
       end
     end
+
+    # Resolve a $ref used where a mapping (path item / operation) is expected.
+    def follow(node)
+      node.is_a?(Reference) ? node.resolve : node
+    end
   end
 end

data/lib/jekyll_openapi/examples.rb

@@ -0,0 +1,75 @@
+require_relative "reference"
+
+module JekyllOpenAPI
+  ##
+  # Flattens the several places and shapes OpenAPI examples take into one list,
+  # so a template never has to care where an example came from.
+  #
+  # Sources, in priority order, for a Parameter or Media Type object:
+  #   1. +examples+        — a map of named Example Objects ({summary, description, value})
+  #   2. +example+         — a single, unnamed value
+  #   3. +schema.examples+ — JSON-Schema examples: an array of values (3.1), or
+  #                          (tolerated) a named map like (1)
+  #   4. +schema.example+  — a single, unnamed value
+  #
+  # The first non-empty source wins — this mirrors the spec's "example XOR
+  # examples" rule while still reaching the schema-level fallback, so callers get
+  # the same result whether examples live on the parameter (3.x style) or on its
+  # schema. Each entry is a plain, string-keyed Hash so it is Liquid-friendly:
+  # {"name", "value", "summary", "description"} (name is nil for unnamed values).
+  module Examples
+    # @param object [Hash, Reference] a Parameter or Media Type object
+    # @return [Array<Hash>] normalized examples ([] when there are none)
+    def self.normalize(object)
+      return [] unless mapping?(object)
+
+      from_map_or_array(object["examples"]) ||
+        from_value(object["example"]) ||
+        from_map_or_array(dig(object, "schema", "examples")) ||
+        from_value(dig(object, "schema", "example")) ||
+        []
+    end
+
+    def self.mapping?(node)
+      node.is_a?(Hash) || node.is_a?(Reference)
+    end
+    private_class_method :mapping?
+
+    def self.dig(object, *keys)
+      object.respond_to?(:dig) ? object.dig(*keys) : nil
+    end
+    private_class_method :dig
+
+    # A map of named Example Objects, or a JSON-Schema array of raw values.
+    def self.from_map_or_array(examples)
+      case examples
+      when Hash
+        return nil if examples.empty?
+        examples.map do |name, example|
+          entry(name, value_of(example), example["summary"], example["description"])
+        end
+      when Array
+        return nil if examples.empty?
+        examples.map { |value| entry(nil, value, nil, nil) }
+      end
+    end
+    private_class_method :from_map_or_array
+
+    def self.from_value(example)
+      return nil if example.nil?
+      [entry(nil, example, nil, nil)]
+    end
+    private_class_method :from_value
+
+    # An Example Object wraps its payload under "value"; a bare scalar is itself.
+    def self.value_of(example)
+      mapping?(example) ? example["value"] : example
+    end
+    private_class_method :value_of
+
+    def self.entry(name, value, summary, description)
+      { "name" => name, "value" => value, "summary" => summary, "description" => description }
+    end
+    private_class_method :entry
+  end
+end

data/lib/jekyll_openapi/filters.rb

@@ -9,7 +9,8 @@ module JekyllOpenAPI
   #
   # or register only a subset by wrapping the methods they want.
   module Filters
-    # Resolve every local $ref in an OpenAPI document (circular-safe)
+    # Replace every local $ref with a lazy, name-preserving Reference. Reads
+    # walk through transparently; recursion and reuse are handled (see Reference).
     def oapi_dereference(input)
       Dereferencer.new(input).dereference
     end
@@ -24,6 +25,13 @@ module JekyllOpenAPI
       Parameters.merge(path_params, operation_params)
     end
 
+    # Normalized example list for a parameter or media-type object, unifying
+    # `examples` (named Example Objects), `example` (single value) and the
+    # schema-level equivalents. Each entry is {name, value, summary, description}.
+    def oapi_examples(input)
+      Examples.normalize(input)
+    end
+
     # Flat operation list from a full document, optionally filtered by tag.
     # See Document#operations for the shape of each entry.
     def oapi_operations(input, tag = nil)
@@ -35,6 +43,21 @@ module JekyllOpenAPI
       document(input).tags
     end
 
+    # Named schema map of a full document (for a "Models" reference section)
+    def oapi_schemas(input)
+      document(input).schemas
+    end
+
+    # Named security scheme map of a full document
+    def oapi_security_schemes(input)
+      document(input).security_schemes
+    end
+
+    # Declared servers of a full document
+    def oapi_servers(input)
+      document(input).servers
+    end
+
     # Render a JSON-Schema as a TypeScript-like string
     def oapi_schema(input)
       SchemaRenderer::TypeScript.render(input)
@@ -45,13 +68,67 @@ module JekyllOpenAPI
       SchemaRenderer::XML.render(input)
     end
 
+    # Render a JSON-Schema as semantic HTML, linking named component schemas to
+    # their #schema-<name> anchor instead of inlining them. Descriptions are
+    # rendered as markdown when a converter is available (inside Jekyll), else as
+    # escaped plain text.
+    def oapi_html_schema(input)
+      SchemaRenderer::HTML.render(input, markdown: markdown_formatter)
+    end
+
+    # Anchor id for a named schema, e.g. "Pet" => "schema-Pet". Use it for the
+    # matching `id` on a Models section so the renderer's links resolve.
+    def oapi_schema_anchor(name)
+      SchemaRenderer::HTML.anchor(name)
+    end
+
+    # Stable fragment id for an operation (entry from `oapi_operations`, or a
+    # bare operationId). Falls back to method+path when operationId is absent.
+    def oapi_operation_anchor(op)
+      Anchors.operation(op)
+    end
+
+    # Stable fragment id for a tag (tag object from `oapi_tags`, or a bare name).
+    def oapi_tag_anchor(tag)
+      Anchors.tag(tag)
+    end
+
+    # Classify a media-type string: "xml" | "json" | "text" | "binary".
+    # Robust to `text/xml`, `application/*+xml`, and `; charset=…` suffixes.
+    def oapi_representation(content_type)
+      ContentType.representation(content_type)
+    end
+
+    # True for XML-family media types (application/xml, text/xml, *+xml).
+    def oapi_is_xml(content_type)
+      ContentType.xml?(content_type)
+    end
+
+    # Normalized header list for a response object: each entry is
+    # {name, description, required, deprecated, schema}. `$ref`'d headers resolve.
+    def oapi_headers(response)
+      Headers.list(response)
+    end
+
     private
 
+    # A `text -> html` markdown converter, or nil when none is reachable. Reuses
+    # whatever `markdownify` filter is mounted alongside us (Jekyll registers
+    # one, and it resolves the site's configured converter via the Liquid
+    # context); outside Jekyll there is none, so descriptions stay plain text.
+    def markdown_formatter
+      return nil unless respond_to?(:markdownify)
+      ->(text) { markdownify(text) }
+    end
+
     # Memoize per input so several filter calls on the same document
-    # (tags, then operations per tag) only dereference it once.
+    # (tags, then operations per tag) only dereference it once. Keyed by object
+    # identity: the hash holds the input as key, so it can't be GC'd and have its
+    # object_id recycled onto a different document (which a bare object_id key
+    # would alias to a stale, wrong Document).
     def document(input)
-      @oapi_documents ||= {}
-      @oapi_documents[input.object_id] ||= Document.new(input)
+      @oapi_documents ||= {}.compare_by_identity
+      @oapi_documents[input] ||= Document.new(input)
     end
   end
 end

data/lib/jekyll_openapi/headers.rb

@@ -0,0 +1,27 @@
+require_relative "reference"
+
+module JekyllOpenAPI
+  ##
+  # Normalizes a Response object's `headers` map into a flat, ordered list —
+  # the Header-object counterpart to Parameters.group. `$ref`'d headers read
+  # transparently through their Reference, so the caller never special-cases them.
+  # @see https://spec.openapis.org/oas/v3.1.0.html#header-object
+  module Headers
+    # @param response [Hash, Reference] a Response object
+    # @return [Array<Hash>] {name, description, required, deprecated, schema}
+    def self.list(response)
+      map = (response.is_a?(Hash) || response.is_a?(Reference)) ? response["headers"] : nil
+      return [] unless map.is_a?(Hash)
+
+      map.map do |name, header|
+        {
+          "name" => name,
+          "description" => header["description"],
+          "required" => header["required"] || false,
+          "deprecated" => header["deprecated"] || false,
+          "schema" => header["schema"],
+        }
+      end
+    end
+  end
+end

data/lib/jekyll_openapi/parameters.rb

@@ -1,3 +1,5 @@
+require_relative "reference"
+
 module JekyllOpenAPI
   ##
   # Helpers for OpenAPI Parameter objects.
@@ -5,6 +7,12 @@ module JekyllOpenAPI
   module Parameters
     LOCATIONS = %w[query path header cookie].freeze
 
+    # A parameter may arrive inline (Hash) or as a $ref (Reference). Both read
+    # like a mapping, so both are valid parameter objects here.
+    def self.mapping?(param)
+      param.is_a?(Hash) || param.is_a?(Reference)
+    end
+
     ##
     # Groups a parameter list by location ("in").
     # Always returns all four location keys so templates can test emptiness.
@@ -13,7 +21,7 @@ module JekyllOpenAPI
     def self.group(params, logger: JekyllOpenAPI.logger)
       output = LOCATIONS.to_h { |location| [location, []] }
       Array(params).each do |param|
-        location = param.is_a?(Hash) ? param["in"] : nil
+        location = mapping?(param) ? param["in"] : nil
         if output.key?(location)
           output[location] << param
         else
@@ -30,7 +38,7 @@ module JekyllOpenAPI
     def self.merge(path_params, operation_params)
       merged = {}
       (Array(path_params) + Array(operation_params)).each do |param|
-        next unless param.is_a?(Hash)
+        next unless mapping?(param)
         merged[[param["name"], param["in"]]] = param
       end
       merged.values