jekyll-openapi 0.1.0 → 0.2.0

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.2.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.2.0
 platform: ruby
 authors:
 - Sebastien Dumetz
@@ -67,12 +67,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