jekyll-openapi 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 989a754db0f9b16a6ddcdc250248e360400b0f7e1cee52c29879f666611036e9
-  data.tar.gz: 1421051366aff8e848f3c451b966a128132ae001e26698e5ea22a99eb9b9afb1
+  metadata.gz: 7c592a43f900f36f1afbfc4432c1dc6b9e55302ec6e481bc6284596a728c36ea
+  data.tar.gz: 047ef58c76751ad0cc91415d838dc367ea302f83b4f88fa95f430397db3563b3
 SHA512:
-  metadata.gz: d1a17b202abcf9defa2200d5c99df7dc8f21f563e0b8166bd5cadc605d91f48a4c56ba18ec37af4eb15f1c3fbf49022bb7e209281a457f7c172bc06b903c9905
-  data.tar.gz: 70aa7e5ad448fc234a1d4c13e66c5cf0cf5ad06d7a8a236e28b90279578b5f36ef74ea316c9f7f05c811aeb4ac363cf0aba91050b4623b1bc570da124b83ddc6
+  metadata.gz: 9a2fe7b1a1ca251142a4592cc1222aed94895e1dd8dbe4d13b7106436e4a50812e08c0756bb5051c24f3918ea99c4e0e348bb46ad9158d89848187c5a9e75c9d
+  data.tar.gz: 93542f7e0c5bdafa05d21442d67044ab751642163571dd01671165a6af69a21fd94461dd96150ea1bbf49b9e3594686194dbca97f3525fe1d33ccec68717b705

data/README.md

@@ -1,7 +1,9 @@
 # jekyll-openapi
 
 A (mostly) spec-compliant [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) toolkit for
-Liquid-based static site generators (Jekyll in particular).
+Liquid-based static site generators (Jekyll in particular), with partial
+[OpenAPI 3.2](https://spec.openapis.org/oas/v3.2.0) support (see
+[OpenAPI 3.2 support](#openapi-32-support)).
 
 It deliberately does **not** render HTML. The gem provides:
 
@@ -75,19 +77,20 @@ title: API Reference
 operation, grouped by tag. That's a complete, working integration.
 
 `oapi_operations` already does the tedious parts for you: it skips
-non-operation path-item keys, handles `x-` extension methods, filters by tag,
-and merges path-level parameters into each operation.
+non-operation path-item keys, handles `x-` extension methods and OpenAPI 3.2
+`additionalOperations`, filters by tag, and merges path-level parameters into
+each operation.
 
 Each `op` in the loop is a plain Hash you can traverse further:
 
 | key                    | content                                              |
 |------------------------|------------------------------------------------------|
 | `"path"`               | `"/pets/{petId}"`                                    |
-| `"method"`             | normalized method, `x-` prefix stripped (`"mkcol"`)  |
-| `"raw_method"`         | the literal key (`"x-mkcol"`)                        |
+| `"method"`             | normalized method, lowercase, `x-` prefix stripped (`"mkcol"`) |
+| `"raw_method"`         | the literal key (`"x-mkcol"`, `"MKCOL"`)             |
 | `"operation"`          | the Operation object, dereferenced                   |
 | `"parameters"`         | path-level + operation-level parameters, merged (operation wins on same name/location) |
-| `"grouped_parameters"` | same, grouped: `{"query" => [...], "path" => [...], "header" => [...], "cookie" => [...]}` |
+| `"grouped_parameters"` | same, grouped: `{"query" => [...], "querystring" => [...], "path" => [...], "header" => [...], "cookie" => [...]}` |
 
 ### Going further
 
@@ -107,17 +110,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 +141,71 @@ 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.
+
+## OpenAPI 3.2 support
+
+Partial. Because the model hands templates plain hashes, most new 3.2 *fields*
+flow through untouched and are usable today; "supported" below means the
+library actively understands the feature, "passthrough" means the raw data
+reaches your template but no helper interprets it.
+
+Supported:
+
+- [x] `additionalOperations` — enumerated by `oapi_operations` like any other
+  operation, with path-level parameters merged; `method` is the lowercased
+  method name, `raw_method` the literal key (`"PROPFIND"`). Gives webDAV-style
+  APIs first-class treatment (previously only reachable via `x-` methods).
+- [x] The `query` HTTP method — recognized as a first-class path-item key.
+- [x] Tag `summary` — passes through `oapi_tags` (tested); use it as a short
+  display name where `description` is prose.
+- [x] `in: querystring` parameters — grouped under their own `"querystring"`
+  key by `oapi_parameters` / `grouped_parameters` (the parameter is
+  `content`-based: render its media-type schema, not a name/value pair). An
+  operation-level querystring parameter overrides a path-level one regardless
+  of name, and mixing it with `in: query` parameters warns (the spec forbids
+  it) but keeps both.
+
+Passthrough (data reaches templates, no helper logic):
+
+- [ ] Tag `parent` / `kind` — the fields are readable, but `oapi_operations`
+  and `oapi_tags` treat tags as a flat list: no hierarchy building, no
+  filtering by kind.
+- [ ] Response `summary`, Server `name` — readable on the raw objects.
+- [ ] Security scheme additions (`deviceAuthorization` flow,
+  `oauth2MetadataUrl`, `deprecated`) — readable via `oapi_security_schemes`.
+
+Not supported (TODO):
+
+- [ ] Streaming / sequential media types — `itemSchema`, `itemEncoding` and
+  `prefixEncoding` are ignored by the schema renderers and `oapi_examples`.
+- [ ] Example Object `dataValue` / `serializedValue` — `oapi_examples` only
+  reads `value`.
+- [ ] `xml.nodeType` — the XML renderer still keys off the 3.1 `attribute` /
+  `wrapped` flags.
+- [ ] `$self` and multi-document descriptions — consistent with the existing
+  local-`$ref`s-only policy.
+- [ ] `components.mediaTypes` reuse — untested; generic local `$ref`
+  resolution may already handle it, but no guarantees.
 
 ## Compliance notes
 
@@ -156,8 +226,8 @@ fidelity":
 rake test          # or: ruby -Ilib -Itest test/test_<name>.rb
 ```
 
-Tests run against generic fixtures (`test/fixtures/petstore.yml`); when the gem
+Tests run against generic fixtures (`test/fixtures/petstore.yml`, a pristine
+OpenAPI 3.1 document, and `test/fixtures/filestore.yml`, a WebDAV-flavored
+OpenAPI 3.2 one); when the gem
 sources live inside the eCorpus_doc repository, an extra integration suite runs
 the whole pipeline over the real eCorpus API definition.
-</content>
-</invoke>

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,9 +9,12 @@ 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
+    HTTP_METHODS = %w[get put post delete options head patch trace query].freeze
     PATH_ITEM_FIELDS = %w[summary description servers parameters $ref].freeze
 
     attr_reader :data
@@ -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,23 +112,56 @@ 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-")
-          next unless operation.is_a?(Hash)
-
-          params = Parameters.merge(path_item["parameters"], operation["parameters"])
-          {
-            "path" => path,
-            "method" => key.delete_prefix("x-"),
-            "raw_method" => key,
-            "operation" => operation,
-            "parameters" => params,
-            "grouped_parameters" => Parameters.group(params, logger: @logger),
-          }
+        path_item.flat_map do |key, value|
+          if key == "additionalOperations"
+            # OpenAPI 3.2: a map of custom HTTP method name => Operation Object.
+            value = follow(value)
+            next [] unless value.is_a?(Hash)
+            value.filter_map do |method, operation|
+              build_operation(path, path_item, method.downcase, method, operation)
+            end
+          else
+            next [] if PATH_ITEM_FIELDS.include?(key)
+            next [] unless HTTP_METHODS.include?(key) || key.start_with?("x-")
+            operation = follow(value)
+            # `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 operation.is_a?(Hash) && key.start_with?("x-") &&
+              !(operation.key?("operationId") || operation.key?("responses"))
+
+            [build_operation(path, path_item, key.delete_prefix("x-"), key, operation)].compact
+          end
         end
       end
     end
+
+    # @return [Hash, nil] a normalized operation entry, or nil when `operation`
+    #   is not an Operation Object
+    def build_operation(path, path_item, method, raw_method, operation)
+      operation = follow(operation)
+      return unless operation.is_a?(Hash)
+
+      params = Parameters.merge(path_item["parameters"], operation["parameters"])
+      {
+        "path" => path,
+        "method" => method,
+        "raw_method" => raw_method,
+        "operation" => operation,
+        "parameters" => params,
+        "grouped_parameters" => Parameters.group(params, logger: @logger),
+      }
+    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