jekyll-openapi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 989a754db0f9b16a6ddcdc250248e360400b0f7e1cee52c29879f666611036e9
+  data.tar.gz: 1421051366aff8e848f3c451b966a128132ae001e26698e5ea22a99eb9b9afb1
+SHA512:
+  metadata.gz: d1a17b202abcf9defa2200d5c99df7dc8f21f563e0b8166bd5cadc605d91f48a4c56ba18ec37af4eb15f1c3fbf49022bb7e209281a457f7c172bc06b903c9905
+  data.tar.gz: 70aa7e5ad448fc234a1d4c13e66c5cf0cf5ad06d7a8a236e28b90279578b5f36ef74ea316c9f7f05c811aeb4ac363cf0aba91050b4623b1bc570da124b83ddc6

data/README.md

@@ -0,0 +1,163 @@
+# 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).
+
+It deliberately does **not** render HTML. The gem provides:
+
+- a navigable **object model** over a parsed OpenAPI document — dereferencing,
+  tag and operation enumeration, parameter merging;
+- **schema-to-text renderers** (TypeScript-like and simplified XML) exposed as
+  opt-in Liquid filters;
+
+…and your site provides the templates. See [examples/](examples/) for complete,
+copy-paste-able templates.
+
+> The gem works as a plain Ruby library too — without Jekyll or Liquid. That
+> usage, the object model, and the renderer API are documented in
+> [examples/ruby/README.md](examples/ruby/README.md).
+
+## Jekyll integration
+
+Add the gem to your `Gemfile` and list it as a plugin — nothing else to do,
+the filters register themselves and warnings are routed to Jekyll's logger:
+
+```ruby
+# Gemfile
+group :plugins do
+  gem "jekyll-openapi"
+end
+```
+
+```yaml
+# _config.yml
+plugins:
+  - jekyll-openapi
+```
+
+## Walkthrough: a minimal API page
+
+Four steps take you from a spec file to a rendered reference page.
+
+**1. Enable the plugin** as shown above (`Gemfile` + `plugins:` entry). No
+`_plugins/` file is needed.
+
+**2. Drop your spec into `_data/`** so Jekyll parses it into `site.data`:
+
+```
+_data/openapi.yml     # YAML or JSON; becomes site.data.openapi
+```
+
+**3. Write a page** that walks the tags and operations with the filters:
+
+```liquid
+---
+title: API Reference
+---
+{% assign api = site.data.openapi %}
+
+<h1>{{ api.info.title }}</h1>
+
+{% assign tags = api | oapi_tags %}
+{% for tag in tags %}
+  <h2>{{ tag.name }}</h2>
+  {{ tag.description | markdownify }}
+
+  {% assign ops = api | oapi_operations: tag.name %}
+  {% for op in ops %}
+    <h3>{{ op.method | upcase }} {{ op.path }}</h3>
+    {{ op.operation.description | markdownify }}
+  {% endfor %}
+{% endfor %}
+```
+
+**4. Build** (`bundle exec jekyll serve`) and you have a page listing every
+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.
+
+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"`)                        |
+| `"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" => [...]}` |
+
+### Going further
+
+The walkthrough above is intentionally bare. For a production-quality page —
+tag index/navigation, parameter tables, request/response bodies with rendered
+schemas — start from the complete examples and restyle them:
+
+- [examples/jekyll/api-doc.html](examples/jekyll/api-doc.html) — a full API
+  reference page: tag cloud, operations grouped by tag, path/query parameter
+  tables, request and response schemas.
+- [examples/jekyll/_includes/oapi/schema.html](examples/jekyll/_includes/oapi/schema.html)
+  — a reusable include that picks the XML or TypeScript renderer based on the
+  content type.
+
+## Liquid filters
+
+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.
+`{{ content.schema | oapi_schema }}` produces:
+
+```typescript
+{
+  name: "string"
+  age?: integer
+}
+```
+
+See [examples/jekyll/_includes/oapi/schema.html](examples/jekyll/_includes/oapi/schema.html)
+for choosing the renderer by content type.
+
+## 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.
+
+## Compliance notes
+
+Intentional simplifications, in the spirit of "readable docs over exhaustive
+fidelity":
+
+- Only **local** (`#/...`) references are resolved; external files/URLs are left as-is.
+- The TypeScript renderer supports `oneOf`/`anyOf` (`|`), `allOf` (`&`),
+  3.1 type arrays (`type: [string, "null"]`), enums, `additionalProperties`,
+  and infers `object`/`array` when `type` is omitted — but does not merge
+  `allOf` members into a single object literal.
+- The XML renderer honors `xml.name`, `xml.prefix`, `xml.namespace`,
+  `xml.attribute` and `xml.wrapped`, and renders example values where provided.
+
+## Development
+
+```sh
+rake test          # or: ruby -Ilib -Itest test/test_<name>.rb
+```
+
+Tests run against generic fixtures (`test/fixtures/petstore.yml`); 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.rb

@@ -0,0 +1,9 @@
+##
+# Gem entry point, matching the gem name so Jekyll's plugin manager can
+# `require "jekyll-openapi"` directly from a `plugins:` config entry.
+require_relative "jekyll_openapi"
+
+# When loaded inside Jekyll, install the filters and logger automatically.
+# Outside Jekyll this is a no-op: register filters yourself with
+# Liquid::Template.register_filter(JekyllOpenAPI::Filters).
+require_relative "jekyll_openapi/jekyll_plugin" if defined?(::Jekyll)

data/lib/jekyll_openapi/dereferencer.rb

@@ -0,0 +1,63 @@
+require_relative "json_pointer"
+
+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.
+  class Dereferencer
+    def initialize(root, logger: JekyllOpenAPI.logger)
+      @root = root
+      @logger = logger
+    end
+
+    def self.dereference(root, logger: JekyllOpenAPI.logger)
+      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 = [])
+      case node
+      when Hash
+        if node.key?("$ref")
+          resolve(node, stack)
+        else
+          node.transform_values { |value| dereference(value, stack) }
+        end
+      when Array
+        node.map { |value| dereference(value, stack) }
+      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

@@ -0,0 +1,100 @@
+require "yaml"
+require "json"
+require_relative "dereferencer"
+require_relative "parameters"
+
+module JekyllOpenAPI
+  ##
+  # Navigable object model over a parsed OpenAPI document.
+  #
+  # 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.
+  class Document
+    HTTP_METHODS = %w[get put post delete options head patch trace].freeze
+    PATH_ITEM_FIELDS = %w[summary description servers parameters $ref].freeze
+
+    attr_reader :data
+
+    # @param data [Hash] a parsed OpenAPI document (dereferenced or not)
+    def initialize(data, logger: JekyllOpenAPI.logger)
+      @data = data
+      @logger = logger
+    end
+
+    # Convenience loader for YAML or JSON files
+    def self.load_file(path, logger: JekyllOpenAPI.logger)
+      data = if File.extname(path) == ".json"
+        JSON.parse(File.read(path))
+      else
+        YAML.safe_load_file(path, aliases: true)
+      end
+      new(data, logger: logger)
+    end
+
+    # @return [Hash] the document with all local $refs resolved (memoized)
+    def dereferenced
+      @dereferenced ||= Dereferencer.new(@data, logger: @logger).dereference
+    end
+
+    def info
+      dereferenced["info"] || {}
+    end
+
+    def tags
+      dereferenced["tags"] || []
+    end
+
+    def paths
+      dereferenced["paths"] || {}
+    end
+
+    ##
+    # Flat list of every operation in the document, in path order.
+    # `x-`-prefixed extension methods (e.g. webDAV verbs) are included,
+    # with the prefix stripped in "method" and kept in "raw_method".
+    #
+    # Each entry is a string-keyed Hash (Liquid-friendly):
+    #   "path"               [String]  e.g. "/scenes/{scene}"
+    #   "method"             [String]  e.g. "get" or "mkcol"
+    #   "raw_method"         [String]  e.g. "get" or "x-mkcol"
+    #   "operation"          [Hash]    the Operation object
+    #   "parameters"         [Array]   path-level and operation-level parameters, merged
+    #   "grouped_parameters" [Hash]    same, grouped by location (see Parameters.group)
+    #
+    # @param tag [String, nil] only operations tagged with this tag
+    def operations(tag: nil)
+      @operations ||= build_operations
+      return @operations unless tag
+      @operations.select { |op| Array(op["operation"]["tags"]).include?(tag) }
+    end
+
+    # @return [Hash{String => Array}] tag name => operations, following the tags declaration order
+    def operations_by_tag
+      tags.to_h { |t| [t["name"], operations(tag: t["name"])] }
+    end
+
+    private
+
+    def build_operations
+      paths.flat_map do |path, 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),
+          }
+        end
+      end
+    end
+  end
+end

data/lib/jekyll_openapi/filters.rb

@@ -0,0 +1,57 @@
+module JekyllOpenAPI
+  ##
+  # Liquid filters over the JekyllOpenAPI model and renderers.
+  #
+  # This module has no dependency on the liquid gem itself: it is a plain
+  # module of filter methods. Consumers opt in with:
+  #
+  #   Liquid::Template.register_filter(JekyllOpenAPI::Filters)
+  #
+  # or register only a subset by wrapping the methods they want.
+  module Filters
+    # Resolve every local $ref in an OpenAPI document (circular-safe)
+    def oapi_dereference(input)
+      Dereferencer.new(input).dereference
+    end
+
+    # Group a parameter list by location: {"query" => [...], "path" => [...], ...}
+    def oapi_parameters(input)
+      Parameters.group(input)
+    end
+
+    # Merge path-level and operation-level parameter lists (operation wins)
+    def oapi_merge_parameters(path_params, operation_params)
+      Parameters.merge(path_params, operation_params)
+    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)
+      document(input).operations(tag: tag)
+    end
+
+    # Tag list of a full document
+    def oapi_tags(input)
+      document(input).tags
+    end
+
+    # Render a JSON-Schema as a TypeScript-like string
+    def oapi_schema(input)
+      SchemaRenderer::TypeScript.render(input)
+    end
+
+    # Render a JSON-Schema as a simplified XML example
+    def oapi_xml_schema(input)
+      SchemaRenderer::XML.render(input)
+    end
+
+    private
+
+    # Memoize per input so several filter calls on the same document
+    # (tags, then operations per tag) only dereference it once.
+    def document(input)
+      @oapi_documents ||= {}
+      @oapi_documents[input.object_id] ||= Document.new(input)
+    end
+  end
+end

data/lib/jekyll_openapi/jekyll_plugin.rb

@@ -0,0 +1,30 @@
+require_relative "../jekyll_openapi"
+
+module JekyllOpenAPI
+  ##
+  # Jekyll integration: registers the Liquid filters and routes warnings to
+  # Jekyll's logger. Loaded automatically when the gem is required inside a
+  # Jekyll site (see lib/jekyll-openapi.rb); kept separate so the core
+  # library stays usable and testable without Jekyll.
+  module JekyllPlugin
+    class LoggerAdapter
+      def warn(message)
+        ::Jekyll.logger.warn("OpenAPI:", message)
+      end
+    end
+
+    def self.register
+      JekyllOpenAPI.logger = LoggerAdapter.new
+      # Liquid 5.x moved filter registration onto the Environment; the
+      # Template method still works but warns. Fall back to it on Liquid 4.x,
+      # which has no Environment.
+      if defined?(::Liquid::Environment)
+        ::Liquid::Environment.default.register_filter(JekyllOpenAPI::Filters)
+      else
+        ::Liquid::Template.register_filter(JekyllOpenAPI::Filters)
+      end
+    end
+  end
+end
+
+JekyllOpenAPI::JekyllPlugin.register

data/lib/jekyll_openapi/json_pointer.rb

@@ -0,0 +1,33 @@
+module JekyllOpenAPI
+  ##
+  # RFC 6901 JSON Pointer resolution.
+  module JSONPointer
+    ##
+    # Resolves a JSON Pointer against a document.
+    # @param doc [Hash, Array] root document
+    # @param pointer [String] e.g. "/components/schemas/Scene"
+    # @return [Object, nil] the referenced value, or nil if not found
+    def self.resolve(doc, pointer)
+      return doc if pointer.nil? || pointer.empty?
+      return nil unless pointer.start_with?("/")
+
+      pointer.split("/", -1).drop(1).reduce(doc) do |node, token|
+        token = unescape(token)
+        case node
+        when Hash
+          node.fetch(token) { return nil }
+        when Array
+          return nil unless /\A\d+\z/.match?(token)
+          node.fetch(Integer(token)) { return nil }
+        else
+          return nil
+        end
+      end
+    end
+
+    # "~1" then "~0", in that order (RFC 6901 §4)
+    def self.unescape(token)
+      token.gsub("~1", "/").gsub("~0", "~")
+    end
+  end
+end

data/lib/jekyll_openapi/parameters.rb

@@ -0,0 +1,39 @@
+module JekyllOpenAPI
+  ##
+  # Helpers for OpenAPI Parameter objects.
+  # @see https://spec.openapis.org/oas/v3.1.0.html#parameter-object
+  module Parameters
+    LOCATIONS = %w[query path header cookie].freeze
+
+    ##
+    # Groups a parameter list by location ("in").
+    # Always returns all four location keys so templates can test emptiness.
+    # @param params [Array<Hash>, nil]
+    # @return [Hash{String => Array<Hash>}]
+    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
+        if output.key?(location)
+          output[location] << param
+        else
+          logger.warn("invalid parameter location #{location.inspect} in #{param.inspect}")
+        end
+      end
+      output
+    end
+
+    ##
+    # Merges path-item level and operation level parameter lists.
+    # An operation parameter overrides a path one with the same (name, in) pair.
+    # @return [Array<Hash>]
+    def self.merge(path_params, operation_params)
+      merged = {}
+      (Array(path_params) + Array(operation_params)).each do |param|
+        next unless param.is_a?(Hash)
+        merged[[param["name"], param["in"]]] = param
+      end
+      merged.values
+    end
+  end
+end

data/lib/jekyll_openapi/schema_renderer/typescript.rb

@@ -0,0 +1,108 @@
+module JekyllOpenAPI
+  module SchemaRenderer
+    ##
+    # Renders a JSON-Schema as a simplified TypeScript-like textual representation.
+    # @see https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00
+    class TypeScript
+      def initialize(logger: JekyllOpenAPI.logger)
+        @logger = logger
+      end
+
+      def self.render(schema, logger: JekyllOpenAPI.logger)
+        new(logger: logger).render(schema)
+      end
+
+      # @param input [Hash] 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}")
+          return ""
+        end
+        str = base(input, prefix)
+        return "" if str.nil?
+        annotate(str, input)
+      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"]
+
+        case type
+        when "object" then object(input, prefix)
+        when "array" then "[ #{render(input["items"], prefix)} ]"
+        when "string" then string(input)
+        when "null" then "null"
+        when nil
+          @logger.warn("not a valid schema object: #{input.inspect}")
+          nil
+        else
+          primitive(input, type)
+        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) }
+        rendered.push("null") if types.include?("null")
+        rendered.join(" | ")
+      end
+
+      def object(input, prefix)
+        str = "{"
+        (input["properties"] || {}).each do |key, schema|
+          required = Array(input["required"]).include?(key)
+          str += "\n#{prefix}  #{key}#{required ? "" : "?"}: #{render(schema, prefix + "  ")}"
+        end
+        props = input["additionalProperties"]
+        if props.is_a?(Hash)
+          str += "\n#{prefix}  [#{props["type"]}]?: #{render(props, prefix + "  ")}"
+        end
+        "#{str}\n#{prefix}}"
+      end
+
+      def string(input)
+        if input["enum"]
+          input["enum"].map { |v| "\"#{v}\"" }.join("|")
+        elsif input["format"] == "binary"
+          "Buffer"
+        else
+          "\"string\""
+        end
+      end
+
+      def primitive(input, type)
+        str = type.to_s
+        str += " (#{input["format"]})" if input["format"]
+        str
+      end
+
+      def annotate(str, input)
+        str = "#{str} // /#{input["pattern"]}/" if input["pattern"]
+        if input["summary"]
+          str = "#{str} //#{input["summary"]}"
+        elsif input["description"]
+          padding = "".rjust(str.length, " ")
+          str = "#{str} //#{input["description"].split("\n").join("\n#{padding} //")}"
+        end
+        str
+      end
+    end
+  end
+end

data/lib/jekyll_openapi/schema_renderer/xml.rb

@@ -0,0 +1,111 @@
+module JekyllOpenAPI
+  module SchemaRenderer
+    ##
+    # Renders a JSON-Schema as a simplified XML representation of the object,
+    # honoring the OpenAPI `xml` metadata object (name, prefix, namespace,
+    # attribute, wrapped).
+    # @see https://spec.openapis.org/oas/v3.1.0.html#xml-object
+    class XML
+      def initialize(logger: JekyllOpenAPI.logger)
+        @logger = logger
+      end
+
+      def self.render(schema, logger: JekyllOpenAPI.logger)
+        new(logger: logger).render(schema)
+      end
+
+      # @param input [Hash] a JSON-Schema
+      # @param prefix [String] current indentation
+      # @param name [String] element name when the schema has no xml.name
+      # @return [String]
+      def render(input, prefix = "", name = "xml")
+        unless input.is_a?(Hash) && (input["type"] || input["properties"] || input["items"])
+          @logger.warn("not a valid schema object: #{input.inspect}")
+          return ""
+        end
+
+        xml_def = input["xml"] || {}
+        name = xml_def["name"] || name
+        name = "#{xml_def["prefix"]}:#{name}" if xml_def["prefix"]
+        attrs = {}
+        if xml_def["namespace"]
+          ns_attr = xml_def["prefix"] ? "xmlns:#{xml_def["prefix"]}" : "xmlns"
+          attrs[ns_attr] = xml_def["namespace"]
+        end
+
+        type = input["type"]
+        type ||= "object" if input["properties"]
+        type ||= "array" if input["items"]
+
+        case type
+        when "array"
+          array(input, prefix, name, attrs, wrapped: xml_def["wrapped"])
+        when "object"
+          content = ""
+          (input["properties"] || {}).each do |key, schema|
+            if schema.is_a?(Hash) && schema.dig("xml", "attribute")
+              attrs[schema.dig("xml", "name") || key] = attribute_value(schema)
+            else
+              content += "\n#{render(schema, prefix + "  ", key)}"
+            end
+          end
+          element(name, attrs, content, prefix)
+        when "string"
+          element(name, attrs, string_content(input), prefix)
+        else
+          content = type.to_s
+          content += comment(" (#{input["format"]})") if input["format"]
+          content += comment(input["summary"]) if input["summary"]
+          element(name, attrs, content, prefix)
+        end
+      end
+
+      private
+
+      def array(input, prefix, name, attrs, wrapped: false)
+        unless wrapped
+          return "#{render(input["items"], prefix, name)}\n#{prefix}#{comment("Array of <#{name}>")}"
+        end
+        item = render(input["items"], prefix + "  ", singular(name))
+        content = "\n#{item}\n#{prefix + "  "}#{comment("Array of <#{singular(name)}>")}"
+        element(name, attrs, content, prefix)
+      end
+
+      def element(name, attrs, content, prefix)
+        str_attrs = attrs.map { |key, value| " #{key}=\"#{value}\"" }.join
+        closing = content.include?("\n") ? "\n#{prefix}" : ""
+        "#{prefix}<#{name}#{str_attrs}>#{content}#{closing}</#{name}>"
+      end
+
+      def string_content(input)
+        content = if input["format"] == "binary"
+          "Buffer"
+        elsif input["example"]
+          input["example"].to_s
+        elsif input["examples"].is_a?(Hash) && !input["examples"].empty?
+          input["examples"].values.first["value"].to_s
+        else
+          "string"
+        end
+        if input["summary"]
+          content += "  #{comment(input["summary"])}"
+        elsif input["pattern"]
+          content += comment("/#{input["pattern"]}/")
+        end
+        content
+      end
+
+      def attribute_value(schema)
+        (schema["example"] || schema["type"] || "string").to_s
+      end
+
+      def singular(name)
+        name.end_with?("s") && name.length > 1 ? name[0..-2] : "item"
+      end
+
+      def comment(str)
+        "<!-- #{str} -->"
+      end
+    end
+  end
+end

data/lib/jekyll_openapi/version.rb

@@ -0,0 +1,3 @@
+module JekyllOpenAPI
+  VERSION = "0.1.0"
+end

data/lib/jekyll_openapi.rb

@@ -0,0 +1,26 @@
+require_relative "jekyll_openapi/version"
+require_relative "jekyll_openapi/json_pointer"
+require_relative "jekyll_openapi/dereferencer"
+require_relative "jekyll_openapi/parameters"
+require_relative "jekyll_openapi/document"
+require_relative "jekyll_openapi/schema_renderer/typescript"
+require_relative "jekyll_openapi/schema_renderer/xml"
+require_relative "jekyll_openapi/filters"
+
+module JekyllOpenAPI
+  # Default logger writes to stderr. Replace with any object responding to
+  # #warn(message), e.g. an adapter around Jekyll.logger.
+  class << self
+    attr_writer :logger
+
+    def logger
+      @logger ||= StderrLogger.new
+    end
+  end
+
+  class StderrLogger
+    def warn(message)
+      Kernel.warn("JekyllOpenAPI: #{message}")
+    end
+  end
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-openapi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sebastien Dumetz
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: liquid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  A (mostly) spec-compliant OpenAPI 3.1 toolkit for Jekyll and other
+  Liquid-based static site generators: a navigable document model
+  (dereferencing, operations, tags, parameters) and schema-to-text
+  renderers (TypeScript-like, XML), exposed as Liquid filters.
+  Self-registers when listed in a Jekyll site's plugins; usable as a
+  plain library elsewhere. HTML rendering is left to the consumer.
+email:
+- s.dumetz@holusion.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/jekyll-openapi.rb
+- lib/jekyll_openapi.rb
+- lib/jekyll_openapi/dereferencer.rb
+- lib/jekyll_openapi/document.rb
+- lib/jekyll_openapi/filters.rb
+- lib/jekyll_openapi/jekyll_plugin.rb
+- lib/jekyll_openapi/json_pointer.rb
+- lib/jekyll_openapi/parameters.rb
+- lib/jekyll_openapi/schema_renderer/typescript.rb
+- lib/jekyll_openapi/schema_renderer/xml.rb
+- lib/jekyll_openapi/version.rb
+homepage: https://github.com/sdumetz/jekyll-openapi
+licenses:
+- Apache-2.0
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.15
+specification_version: 4
+summary: OpenAPI 3.1 object model and schema renderers for Jekyll
+test_files: []