jekyll-openapi 0.1.0 → 0.3.0

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

data/lib/jekyll_openapi/schema_renderer/xml.rb

@@ -1,9 +1,11 @@
+require_relative "../schema"
+
 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).
+    # attribute, wrapped). Traversal and `$ref` following live in {Schema}.
     # @see https://spec.openapis.org/oas/v3.1.0.html#xml-object
     class XML
       def initialize(logger: JekyllOpenAPI.logger)
@@ -14,17 +16,27 @@ 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
       # @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}")
+        schema = Schema.wrap(input)
+
+        if schema.reference?
+          followed = schema.follow
+          # A cyclic or unresolvable ref has no finite XML expansion here.
+          return "" if followed.nil? || followed == Schema::CYCLE
+          return render(followed, prefix, name)
+        end
+
+        unless schema.mapping? &&
+            (schema.declared_type || schema["properties"] || schema["items"] || schema["additionalProperties"])
+          @logger.warn("not a valid schema object: #{schema.raw.inspect}")
           return ""
         end
 
-        xml_def = input["xml"] || {}
+        xml_def = schema.xml
         name = xml_def["name"] || name
         name = "#{xml_def["prefix"]}:#{name}" if xml_def["prefix"]
         attrs = {}
@@ -33,40 +45,44 @@ module JekyllOpenAPI
           attrs[ns_attr] = xml_def["namespace"]
         end
 
-        type = input["type"]
-        type ||= "object" if input["properties"]
-        type ||= "array" if input["items"]
+        type = schema.declared_type
+        # A 3.1 type union (e.g. ["string","null"]) prints as one sample element:
+        # take the first non-null member rather than stringifying the array.
+        type = (type - ["null"]).first if type.is_a?(Array)
+        type ||= "object" if schema["properties"] || schema["additionalProperties"]
+        type ||= "array" if schema["items"]
 
         case type
         when "array"
-          array(input, prefix, name, attrs, wrapped: xml_def["wrapped"])
+          array(schema, 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)
+          schema.properties.each do |key, property|
+            if property.dig("xml", "attribute")
+              attrs[property.dig("xml", "name") || key] = attribute_value(property)
             else
-              content += "\n#{render(schema, prefix + "  ", key)}"
+              content += "\n#{render(property, prefix + "  ", key)}"
             end
           end
           element(name, attrs, content, prefix)
         when "string"
-          element(name, attrs, string_content(input), prefix)
+          element(name, attrs, string_content(schema), prefix)
         else
           content = type.to_s
-          content += comment(" (#{input["format"]})") if input["format"]
-          content += comment(input["summary"]) if input["summary"]
+          content += comment(" (#{schema.format})") if schema.format
+          content += comment(schema.summary) if schema.summary
           element(name, attrs, content, prefix)
         end
       end
 
       private
 
-      def array(input, prefix, name, attrs, wrapped: false)
+      def array(schema, prefix, name, attrs, wrapped: false)
+        items = schema.items
         unless wrapped
-          return "#{render(input["items"], prefix, name)}\n#{prefix}#{comment("Array of <#{name}>")}"
+          return "#{render(items, prefix, name)}\n#{prefix}#{comment("Array of <#{name}>")}"
         end
-        item = render(input["items"], prefix + "  ", singular(name))
+        item = render(items, prefix + "  ", singular(name))
         content = "\n#{item}\n#{prefix + "  "}#{comment("Array of <#{singular(name)}>")}"
         element(name, attrs, content, prefix)
       end
@@ -77,20 +93,23 @@ module JekyllOpenAPI
         "#{prefix}<#{name}#{str_attrs}>#{content}#{closing}</#{name}>"
       end
 
-      def string_content(input)
-        content = if input["format"] == "binary"
+      def string_content(schema)
+        content = if schema.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
+        elsif !schema.example.nil?
+          schema.example.to_s
+        elsif schema.examples.is_a?(Array) && !schema.examples.empty?
+          # OpenAPI 3.1 / JSON-Schema: a schema's `examples` is an array of values.
+          # The Example Object *map* is a media-type/parameter construct, not valid
+          # on a schema, so it is deliberately not interpreted here.
+          schema.examples.first.to_s
         else
           "string"
         end
-        if input["summary"]
-          content += "  #{comment(input["summary"])}"
-        elsif input["pattern"]
-          content += comment("/#{input["pattern"]}/")
+        if schema.summary
+          content += "  #{comment(schema.summary)}"
+        elsif schema.pattern
+          content += comment("/#{schema.pattern}/")
         end
         content
       end

data/lib/jekyll_openapi/version.rb

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

data/lib/jekyll_openapi.rb

@@ -1,10 +1,17 @@
 require_relative "jekyll_openapi/version"
 require_relative "jekyll_openapi/json_pointer"
+require_relative "jekyll_openapi/reference"
 require_relative "jekyll_openapi/dereferencer"
 require_relative "jekyll_openapi/parameters"
+require_relative "jekyll_openapi/examples"
+require_relative "jekyll_openapi/anchors"
+require_relative "jekyll_openapi/content_type"
+require_relative "jekyll_openapi/headers"
+require_relative "jekyll_openapi/schema"
 require_relative "jekyll_openapi/document"
 require_relative "jekyll_openapi/schema_renderer/typescript"
 require_relative "jekyll_openapi/schema_renderer/xml"
+require_relative "jekyll_openapi/schema_renderer/html"
 require_relative "jekyll_openapi/filters"
 
 module JekyllOpenAPI

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-openapi
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Sebastien Dumetz
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: liquid
   requirement: !ruby/object:Gem::Requirement
@@ -67,12 +81,19 @@ files:
 - README.md
 - lib/jekyll-openapi.rb
 - lib/jekyll_openapi.rb
+- lib/jekyll_openapi/anchors.rb
+- lib/jekyll_openapi/content_type.rb
 - lib/jekyll_openapi/dereferencer.rb
 - lib/jekyll_openapi/document.rb
+- lib/jekyll_openapi/examples.rb
 - lib/jekyll_openapi/filters.rb
+- lib/jekyll_openapi/headers.rb
 - lib/jekyll_openapi/jekyll_plugin.rb
 - lib/jekyll_openapi/json_pointer.rb
 - lib/jekyll_openapi/parameters.rb
+- lib/jekyll_openapi/reference.rb
+- lib/jekyll_openapi/schema.rb
+- lib/jekyll_openapi/schema_renderer/html.rb
 - lib/jekyll_openapi/schema_renderer/typescript.rb
 - lib/jekyll_openapi/schema_renderer/xml.rb
 - lib/jekyll_openapi/version.rb