jekyll-openapi 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 115a158c4677920431b493e1d8941d8bc84f7ac71f0d9813f386ed9a1391878d
-  data.tar.gz: 2444e2822f9181d34c4ade929b0903861d43ea6b9a9376db09baef3abe779906
+  metadata.gz: 7c592a43f900f36f1afbfc4432c1dc6b9e55302ec6e481bc6284596a728c36ea
+  data.tar.gz: 047ef58c76751ad0cc91415d838dc367ea302f83b4f88fa95f430397db3563b3
 SHA512:
-  metadata.gz: 800e3dd82c5c47f0b5b1e31319199ffc5045eb72ebc5285062ab2ecb0e831bcb56a842b7fd168bd239b9b4ac194056c1a2d059650361f6cf484857ac3d0704de
-  data.tar.gz: 677f5f4053e77ec018823e08e24cf89e3a2b44c70ea5267368eee22e83195407872487f134646743a2dcfca9bc78d284501b3140e12c771598e0bfa4bca0e1fc
+  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
 
@@ -159,6 +162,51 @@ 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
 
 Intentional simplifications, in the spirit of "readable docs over exhaustive
@@ -178,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/document.rb

@@ -14,7 +14,7 @@ module JekyllOpenAPI
   # 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
@@ -116,32 +116,49 @@ module JekyllOpenAPI
         # 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"])
-          {
-            "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

data/lib/jekyll_openapi/parameters.rb

@@ -5,7 +5,9 @@ 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
+    # "querystring" is OpenAPI 3.2: a single parameter describing the entire
+    # query string through `content` (its `name` is not used in serialization).
+    LOCATIONS = %w[query querystring 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.
@@ -15,7 +17,7 @@ module JekyllOpenAPI
 
     ##
     # Groups a parameter list by location ("in").
-    # Always returns all four location keys so templates can test emptiness.
+    # Always returns all five location keys so templates can test emptiness.
     # @param params [Array<Hash>, nil]
     # @return [Hash{String => Array<Hash>}]
     def self.group(params, logger: JekyllOpenAPI.logger)
@@ -28,18 +30,24 @@ module JekyllOpenAPI
           logger.warn("invalid parameter location #{location.inspect} in #{param.inspect}")
         end
       end
+      unless output["querystring"].empty? || output["query"].empty?
+        logger.warn("`in: querystring` must not be combined with `in: query` parameters")
+      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.
+    # A querystring parameter overrides on location alone: its name is not used
+    # in serialization and only one may describe the query string.
     # @return [Array<Hash>]
     def self.merge(path_params, operation_params)
       merged = {}
       (Array(path_params) + Array(operation_params)).each do |param|
         next unless mapping?(param)
-        merged[[param["name"], param["in"]]] = param
+        name = param["in"] == "querystring" ? nil : param["name"]
+        merged[[name, param["in"]]] = param
       end
       merged.values
     end

data/lib/jekyll_openapi/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-openapi
 version: !ruby/object:Gem::Version
-  version: 0.2.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