openapi_parser 2.5.0 → 2.6.0

data/lib/openapi_parser/schemas/path_item.rb

@@ -3,20 +3,46 @@
 
 module OpenAPIParser::Schemas
   class PathItem < Base
+    # `query` is an OpenAPI 3.2 addition
+    STANDARD_METHODS = %w[get put post delete options head patch trace query].freeze
+    PRE_3_2_METHODS = (STANDARD_METHODS - %w[query]).freeze
+
     openapi_attr_values :summary, :description
 
-    openapi_attr_objects :get, :put, :post, :delete, :options, :head, :patch, :trace, Operation
+    openapi_attr_objects :get, :put, :post, :delete, :options, :head, :patch, :trace, :query, Operation
     openapi_attr_list_object :parameters, Parameter, reference: true
 
-    # @return [Operation]
+    # @!attribute [r] additional_operations
+    #   @return [Hash{String => Operation}, nil] operations for non-standard HTTP methods (OpenAPI 3.2+)
+    openapi_attr_hash_object :additional_operations, Operation, reference: false, schema_key: :additionalOperations
+
+    # @return [Operation, nil]
     def operation(method)
-      public_send(method)
-    rescue NoMethodError
-      nil
+      # before 3.2: exact-case standard methods only, as it always was
+      unless root.use_3_2_features?
+        return PRE_3_2_METHODS.include?(method.to_s) ? public_send(method.to_s) : nil
+      end
+
+      method_name = method.to_s.downcase
+      return public_send(method_name) if STANDARD_METHODS.include?(method_name)
+
+      additional_operation(method.to_s)
     end
 
     def set_path_item_to_operation
-      [:get, :put, :post, :delete, :options, :head, :patch, :trace].each{ |method| operation(method)&.set_parent_path_item(self)}
+      STANDARD_METHODS.each { |method| operation(method)&.set_parent_path_item(self) }
+      additional_operations&.each_value { |op| op.set_parent_path_item(self) }
     end
+
+    private
+
+      # additionalOperations keys are method names as sent on the wire
+      # (conventionally uppercase); prefer an exact match, else ignore case
+      def additional_operation(name)
+        operations = additional_operations
+        return nil unless operations
+
+        operations.fetch(name) { operations.find { |key, _| key.casecmp?(name) }&.last }
+      end
   end
 end

data/lib/openapi_parser/schemas/request_body.rb

@@ -12,7 +12,7 @@ module OpenAPIParser::Schemas
 
     # @!attribute [r] content
     #   @return [Hash{String => MediaType}, nil] content type to MediaType object
-    openapi_attr_hash_object :content, MediaType, reference: false
+    openapi_attr_hash_object :content, MediaType, reference: OpenAPIParser::MediaTypeSelectable::CONTENT_REFERENCE
 
     # @param [String] content_type
     # @param [Hash] params

data/lib/openapi_parser/schemas/response.rb

@@ -6,9 +6,13 @@ module OpenAPIParser::Schemas
 
     openapi_attr_values :description
 
+    # @!attribute [r] summary
+    #   @return [String, nil] short summary of the response (OpenAPI 3.2+)
+    openapi_attr_value :summary
+
     # @!attribute [r] content
     #   @return [Hash{String => MediaType}, nil] content_type to MediaType hash
-    openapi_attr_hash_object :content, MediaType, reference: false
+    openapi_attr_hash_object :content, MediaType, reference: OpenAPIParser::MediaTypeSelectable::CONTENT_REFERENCE
 
     # @!attribute [r] headers
     #   @return [Hash{String => Header}, nil] header string to Header

data/lib/openapi_parser/schemas/schema.rb

@@ -1,4 +1,3 @@
-# TODO: support 'not' because I need check reference...
 # TODO: support 'xml', 'externalDocs'
 # TODO: support extended property
 
@@ -96,6 +95,10 @@ module OpenAPIParser::Schemas
     #   @return [Array<Schema, Reference>, nil]
     openapi_attr_list_object :any_of, Schema, reference: true, schema_key: :anyOf
 
+    # @!attribute [r] not
+    #   @return [Schema, nil]
+    openapi_attr_object :not, Schema, reference: true
+
     # @!attribute [r] items
     #   @return [Schema, nil]
     openapi_attr_object :items, Schema, reference: true
@@ -112,6 +115,10 @@ module OpenAPIParser::Schemas
     #   @return [Hash{String => Schema}, nil]
     openapi_attr_hash_object :properties, Schema, reference: true
 
+    # @!attribute [r] defs
+    #   @return [Hash{String => Schema}, nil] reusable schemas for `$ref` (OpenAPI 3.1+)
+    openapi_attr_hash_object :defs, Schema, reference: true, schema_key: :$defs
+
     # @!attribute [r] discriminator
     #   @return [Discriminator, nil]
     openapi_attr_object :discriminator, Discriminator

data/lib/openapi_parser/spec_validator/rule.rb

@@ -46,12 +46,33 @@ module OpenAPIParser
         def each_schema(root, &block)
           return enum_for(:each_schema, root) unless block
 
-          visited = {}
-          walk(root, visited) do |node|
-            yield node if node.is_a?(OpenAPIParser::Schemas::Schema)
+          each_node(root, OpenAPIParser::Schemas::Schema, &block)
+        end
+
+        # yields every parsed object reachable from root that is one of klasses
+        def each_node(root, *klasses)
+          walk(root, {}) do |node|
+            yield node if klasses.any? { |klass| node.is_a?(klass) }
+          end
+        end
+
+        # security schemes are not modeled by the parse layer, so rules
+        # about them read the raw `components.securitySchemes` map
+        def each_security_scheme(root)
+          components = root.raw_schema.is_a?(Hash) ? root.raw_schema['components'] : nil
+          schemes = components.is_a?(Hash) ? components['securitySchemes'] : nil
+          return unless schemes.is_a?(Hash)
+
+          schemes.each do |name, scheme|
+            yield(name, scheme) if scheme.is_a?(Hash)
           end
         end
 
+        # escapes a map key for use in a violation path, matching object_reference
+        def escape_reference(key)
+          key.to_s.gsub('~', '~0').gsub('/', '~1')
+        end
+
         def walk(node, visited, &block)
           return unless node.respond_to?(:_openapi_all_child_objects)
           return if visited[node.object_id]

data/lib/openapi_parser/spec_validator/rules/additional_operations_before_32.rb

@@ -0,0 +1,26 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `additionalOperations` is a 3.2 Path Item addition for non-standard
+      # HTTP methods. The parse layer accepts it permissively; this rule
+      # reports the version mismatch.
+      class AdditionalOperationsBefore32 < Rule
+        def check(root)
+          return [] unless version_before?('3.2')
+
+          violations = []
+          each_node(root, OpenAPIParser::Schemas::PathItem) do |node|
+            raw = node.raw_schema
+            next unless raw.is_a?(Hash) && raw.key?('additionalOperations')
+
+            violations << violation(
+              path: "#{node.object_reference}/additionalOperations",
+              message: '`additionalOperations` is a 3.2 Path Item addition; earlier documents have no such field',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/allow_empty_value_deprecation.rb

@@ -0,0 +1,26 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # 3.2 deprecates `allowEmptyValue` on the Parameter Object (3.1 only
+      # called it NOT RECOMMENDED). The field is still allowed but
+      # discouraged, so we report it as a violation on 3.2 documents.
+      class AllowEmptyValueDeprecation < Rule
+        def check(root)
+          return [] unless version_at_least?('3.2')
+
+          violations = []
+          each_node(root, OpenAPIParser::Schemas::Parameter) do |node|
+            raw = node.raw_schema
+            next unless raw.is_a?(Hash) && raw.key?('allowEmptyValue')
+
+            violations << violation(
+              path: "#{node.object_reference}/allowEmptyValue",
+              message: '`allowEmptyValue` on a Parameter Object is deprecated in 3.2',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/cookie_style_before_32.rb

@@ -0,0 +1,26 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `style: cookie` is a 3.2 Parameter style for cookie serialization.
+      # Runtime validation ignores `style`; this rule reports the version
+      # mismatch.
+      class CookieStyleBefore32 < Rule
+        def check(root)
+          return [] unless version_before?('3.2')
+
+          violations = []
+          each_node(root, OpenAPIParser::Schemas::Parameter) do |node|
+            raw = node.raw_schema
+            next unless raw.is_a?(Hash) && raw['style'] == 'cookie'
+
+            violations << violation(
+              path: "#{node.object_reference}/style",
+              message: '`style: cookie` is a 3.2 Parameter style; earlier documents have no such style',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/default_mapping_before_32.rb

@@ -0,0 +1,29 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `defaultMapping` on the Discriminator Object is a 3.2 addition. The
+      # parse layer accepts it permissively; this rule reports the version
+      # mismatch.
+      class DefaultMappingBefore32 < Rule
+        def check(root)
+          return [] unless version_before?('3.2')
+
+          violations = []
+          each_schema(root) do |schema|
+            raw = schema.raw_schema
+            next unless raw.is_a?(Hash)
+
+            discriminator = raw['discriminator']
+            next unless discriminator.is_a?(Hash) && discriminator.key?('defaultMapping')
+
+            violations << violation(
+              path: "#{schema.object_reference}/discriminator/defaultMapping",
+              message: '`defaultMapping` on a Discriminator Object is a 3.2 addition; earlier documents have no such field',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/defs_in_30.rb

@@ -0,0 +1,25 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `$defs` is a JSON Schema 2020-12 keyword that 3.1 adopted. 3.0
+      # Schema Objects do not define it. The parse layer resolves `$ref`s
+      # into it regardless of version; this rule reports the version mismatch.
+      class DefsIn30 < Rule
+        def check(root)
+          return [] unless version_before?('3.1')
+
+          violations = []
+          each_schema(root) do |schema|
+            next unless schema.raw_schema.is_a?(Hash) && schema.raw_schema.key?('$defs')
+
+            violations << violation(
+              path: schema.object_reference,
+              message: '`$defs` is a 3.1 addition (from JSON Schema 2020-12); 3.0 Schema Objects do not define it',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/example_value_fields_before_32.rb

@@ -0,0 +1,48 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # 3.2 adds `dataValue` and `serializedValue` to the Example Object.
+      # Example Objects are not modeled by the parse layer, so this rule
+      # inspects the raw `examples` maps on Parameter, Media Type, and
+      # Header objects, plus `components.examples`. Media Types under a
+      # Parameter or Header `content` and anything under callbacks are not
+      # modeled, so examples there are not reached.
+      class ExampleValueFieldsBefore32 < Rule
+        NEW_FIELDS = %w[dataValue serializedValue].freeze
+
+        def check(root)
+          return [] unless version_before?('3.2')
+
+          violations = []
+          node_classes = [
+            OpenAPIParser::Schemas::Parameter,
+            OpenAPIParser::Schemas::MediaType,
+            OpenAPIParser::Schemas::Header,
+            OpenAPIParser::Schemas::Components,
+          ]
+          each_node(root, *node_classes) do |node|
+            raw = node.raw_schema
+            next unless raw.is_a?(Hash)
+
+            examples = raw['examples']
+            next unless examples.is_a?(Hash)
+
+            examples.each do |name, example|
+              next unless example.is_a?(Hash)
+
+              NEW_FIELDS.each do |field|
+                next unless example.key?(field)
+
+                violations << violation(
+                  path: "#{node.object_reference}/examples/#{escape_reference(name)}/#{field}",
+                  message: "`#{field}` on an Example Object is a 3.2 addition; earlier documents have no such field",
+                )
+              end
+            end
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/media_types_before_32.rb

@@ -0,0 +1,24 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `components.mediaTypes` is a 3.2 addition. The parse layer accepts
+      # it permissively; this rule reports the version mismatch.
+      class MediaTypesBefore32 < Rule
+        def check(root)
+          return [] unless version_before?('3.2')
+
+          components = root.components
+          return [] unless components
+
+          raw = components.raw_schema
+          return [] unless raw.is_a?(Hash) && raw.key?('mediaTypes')
+
+          [violation(
+            path: "#{components.object_reference}/mediaTypes",
+            message: '`components.mediaTypes` is a 3.2 addition; earlier documents should not declare it',
+          )]
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/query_method_before_32.rb

@@ -0,0 +1,26 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `query` is a 3.2 Path Item addition for the HTTP QUERY method. The
+      # parse layer accepts it permissively; this rule reports the version
+      # mismatch.
+      class QueryMethodBefore32 < Rule
+        def check(root)
+          return [] unless version_before?('3.2')
+
+          violations = []
+          each_node(root, OpenAPIParser::Schemas::PathItem) do |node|
+            raw = node.raw_schema
+            next unless raw.is_a?(Hash) && raw.key?('query')
+
+            violations << violation(
+              path: "#{node.object_reference}/query",
+              message: 'the `query` operation is a 3.2 Path Item addition; earlier documents have no such field',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/querystring_before_32.rb

@@ -0,0 +1,26 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `in: querystring` is a 3.2 Parameter location that treats the whole
+      # query string as one value described by `content`. Runtime validation
+      # does not support it yet; this rule reports the version mismatch.
+      class QuerystringBefore32 < Rule
+        def check(root)
+          return [] unless version_before?('3.2')
+
+          violations = []
+          each_node(root, OpenAPIParser::Schemas::Parameter) do |node|
+            raw = node.raw_schema
+            next unless raw.is_a?(Hash) && raw['in'] == 'querystring'
+
+            violations << violation(
+              path: "#{node.object_reference}/in",
+              message: '`in: querystring` is a 3.2 Parameter location; earlier documents have no such location',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/response_summary_before_32.rb

@@ -0,0 +1,25 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # 3.2 adds `summary` to the Response Object. The parse layer accepts it
+      # permissively; this rule reports the version mismatch.
+      class ResponseSummaryBefore32 < Rule
+        def check(root)
+          return [] unless version_before?('3.2')
+
+          violations = []
+          each_node(root, OpenAPIParser::Schemas::Response) do |node|
+            raw = node.raw_schema
+            next unless raw.is_a?(Hash) && raw.key?('summary')
+
+            violations << violation(
+              path: "#{node.object_reference}/summary",
+              message: '`summary` on a Response Object is a 3.2 addition; earlier documents have no such field',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/security_scheme_fields_before_32.rb

@@ -0,0 +1,41 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # 3.2 adds `deprecated` and `oauth2MetadataUrl` to the Security Scheme
+      # Object and the `deviceAuthorization` OAuth flow. Security schemes are
+      # not modeled by the parse layer, so this rule inspects the raw
+      # `components.securitySchemes` map; schemes given as a `$ref` are not
+      # followed.
+      class SecuritySchemeFieldsBefore32 < Rule
+        NEW_FIELDS = %w[deprecated oauth2MetadataUrl].freeze
+
+        def check(root)
+          return [] unless version_before?('3.2')
+
+          violations = []
+          each_security_scheme(root) do |name, scheme|
+            base = "#/components/securitySchemes/#{escape_reference(name)}"
+
+            NEW_FIELDS.each do |field|
+              next unless scheme.key?(field)
+
+              violations << violation(
+                path: "#{base}/#{field}",
+                message: "`#{field}` on a Security Scheme Object is a 3.2 addition; earlier documents have no such field",
+              )
+            end
+
+            flows = scheme['flows']
+            next unless flows.is_a?(Hash) && flows.key?('deviceAuthorization')
+
+            violations << violation(
+              path: "#{base}/flows/deviceAuthorization",
+              message: 'the `deviceAuthorization` OAuth flow is a 3.2 addition; earlier documents have no such flow',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/server_name_before_32.rb

@@ -0,0 +1,35 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # 3.2 adds `name` to the Server Object. Servers are not modeled by
+      # the parse layer, so this rule inspects the raw `servers` arrays on
+      # the root, Path Item, and Operation objects. Servers under callbacks
+      # and Link Objects are not reached.
+      class ServerNameBefore32 < Rule
+        def check(root)
+          return [] unless version_before?('3.2')
+
+          violations = []
+          node_classes = [OpenAPIParser::Schemas::OpenAPI, OpenAPIParser::Schemas::PathItem, OpenAPIParser::Schemas::Operation]
+          each_node(root, *node_classes) do |node|
+            raw = node.raw_schema
+            next unless raw.is_a?(Hash)
+
+            servers = raw['servers']
+            next unless servers.is_a?(Array)
+
+            servers.each_with_index do |server, index|
+              next unless server.is_a?(Hash) && server.key?('name')
+
+              violations << violation(
+                path: "#{node.object_reference}/servers/#{index}/name",
+                message: '`name` on a Server Object is a 3.2 addition; earlier documents have no such field',
+              )
+            end
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/streaming_fields_before_32.rb

@@ -0,0 +1,56 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # 3.2 adds `itemSchema`, `itemEncoding`, and `prefixEncoding` to the
+      # Media Type Object for sequential media types (SSE, JSON Lines,
+      # JSON Sequences), and lets an Encoding Object nest `encoding`,
+      # `itemEncoding`, and `prefixEncoding`. The parse layer accepts
+      # `itemSchema` permissively; this rule reports the version mismatch.
+      # Media Types under a Parameter or Header `content` are not modeled,
+      # so fields there are not reached.
+      class StreamingFieldsBefore32 < Rule
+        NEW_FIELDS = %w[itemSchema itemEncoding prefixEncoding].freeze
+        NEW_ENCODING_FIELDS = %w[encoding itemEncoding prefixEncoding].freeze
+
+        def check(root)
+          return [] unless version_before?('3.2')
+
+          violations = []
+          each_node(root, OpenAPIParser::Schemas::MediaType) do |node|
+            raw = node.raw_schema
+            next unless raw.is_a?(Hash)
+
+            NEW_FIELDS.each do |field|
+              next unless raw.key?(field)
+
+              violations << violation(
+                path: "#{node.object_reference}/#{field}",
+                message: "`#{field}` on a Media Type Object is a 3.2 addition; earlier documents have no such field",
+              )
+            end
+
+            violations.concat(encoding_violations(node, raw['encoding']))
+          end
+          violations
+        end
+
+        private
+
+          def encoding_violations(node, encodings)
+            return [] unless encodings.is_a?(Hash)
+
+            encodings.flat_map do |property, encoding|
+              next [] unless encoding.is_a?(Hash)
+
+              NEW_ENCODING_FIELDS.select { |field| encoding.key?(field) }.map do |field|
+                violation(
+                  path: "#{node.object_reference}/encoding/#{escape_reference(property)}/#{field}",
+                  message: "`#{field}` on an Encoding Object is a 3.2 addition; earlier documents have no such field",
+                )
+              end
+            end
+          end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/tag_fields_before_32.rb

@@ -0,0 +1,34 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # 3.2 adds `summary`, `parent`, and `kind` to the Tag Object.
+      # Tags are not modeled by the parse layer, so this rule inspects the
+      # raw root-level `tags` array.
+      class TagFieldsBefore32 < Rule
+        NEW_FIELDS = %w[summary parent kind].freeze
+
+        def check(root)
+          return [] unless version_before?('3.2')
+
+          tags = root.raw_schema.is_a?(Hash) ? root.raw_schema['tags'] : nil
+          return [] unless tags.is_a?(Array)
+
+          violations = []
+          tags.each_with_index do |tag, index|
+            next unless tag.is_a?(Hash)
+
+            NEW_FIELDS.each do |field|
+              next unless tag.key?(field)
+
+              violations << violation(
+                path: "#/tags/#{index}/#{field}",
+                message: "`#{field}` on a Tag Object is a 3.2 addition; earlier documents have no such field",
+              )
+            end
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/xml_attribute_deprecation.rb

@@ -0,0 +1,29 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # 3.2 deprecates `attribute: true` on the XML Object in favor of
+      # `nodeType: attribute`. The field is still allowed but discouraged,
+      # so we report it as a violation on 3.2 documents.
+      class XmlAttributeDeprecation < Rule
+        def check(root)
+          return [] unless version_at_least?('3.2')
+
+          violations = []
+          each_schema(root) do |schema|
+            raw = schema.raw_schema
+            next unless raw.is_a?(Hash)
+
+            xml = raw['xml']
+            next unless xml.is_a?(Hash) && xml['attribute'] == true
+
+            violations << violation(
+              path: schema.object_reference,
+              message: '`attribute` on an XML Object is deprecated in 3.2; use `nodeType: attribute`',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/xml_node_type_before_32.rb

@@ -0,0 +1,29 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # 3.2 adds `nodeType` to the XML Object (replacing `attribute` and
+      # `wrapped`). XML Objects are not modeled by the parse layer, so this
+      # rule inspects the raw `xml` field on schemas.
+      class XmlNodeTypeBefore32 < Rule
+        def check(root)
+          return [] unless version_before?('3.2')
+
+          violations = []
+          each_schema(root) do |schema|
+            raw = schema.raw_schema
+            next unless raw.is_a?(Hash)
+
+            xml = raw['xml']
+            next unless xml.is_a?(Hash) && xml.key?('nodeType')
+
+            violations << violation(
+              path: schema.object_reference,
+              message: '`nodeType` on an XML Object is a 3.2 addition; earlier documents have no such field',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end