Detect Parameter in: querystring in pre-3.2 documents (QuerystringBefore32 rule)

CHANGELOG.md

@@ -33,6 +33,7 @@
   * `DefaultMappingBefore32`: detect Discriminator `defaultMapping` usage in pre-3.2 documents (3.2 addition)
   * `QueryMethodBefore32`: detect Path Item `query` usage in pre-3.2 documents (3.2 addition)
   * `AdditionalOperationsBefore32`: detect Path Item `additionalOperations` usage in pre-3.2 documents (3.2 addition)
+  * `QuerystringBefore32`: detect Parameter `in: querystring` usage in pre-3.2 documents (3.2 addition; not validated at runtime)
 * expose the declared version as `OpenAPI#openapi_version` (a `Gem::Version`, or nil when the field is missing or malformed) so `SpecValidator` rules compare version ranges; a 3.2 document is checked by the 3.1-or-later rules
 * support 3.1-style numeric `exclusiveMinimum` / `exclusiveMaximum` in value validation (standalone bound, not a Boolean modifier on `minimum` / `maximum`)
 * support `type: "null"` (3.1 primitive) in value validation

lib/openapi_parser/spec_validator.rb

@@ -29,6 +29,7 @@
 require_relative 'spec_validator/rules/default_mapping_before_32'
 require_relative 'spec_validator/rules/query_method_before_32'
 require_relative 'spec_validator/rules/additional_operations_before_32'
+require_relative 'spec_validator/rules/querystring_before_32'
 
 module OpenAPIParser
   class SpecViolationError < OpenAPIError
@@ -105,6 +106,7 @@ def rules
           Rules::DefaultMappingBefore32,
           Rules::QueryMethodBefore32,
           Rules::AdditionalOperationsBefore32,
+          Rules::QuerystringBefore32,
         ]
       end
   end

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

sig/openapi_parser/spec_validator.rbs

@@ -163,6 +163,10 @@ module OpenAPIParser
       class AdditionalOperationsBefore32 < Rule
         def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
       end
+
+      class QuerystringBefore32 < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
     end
   end
 

spec/data/openapi_3_2/querystring_31.yaml

@@ -0,0 +1,20 @@
+openapi: 3.1.0
+info:
+  title: Pet API
+  version: '1.0'
+paths:
+  /pets:
+    get:
+      summary: List pets
+      parameters:
+        # `in: querystring` is a 3.2 Parameter location; a 3.1 document has
+        # no such location, so its use here is a spec violation.
+        - name: q
+          in: querystring
+          content:
+            application/x-www-form-urlencoded:
+              schema:
+                type: object
+      responses:
+        '200':
+          description: OK

spec/data/openapi_3_2/querystring_32.yaml

@@ -0,0 +1,18 @@
+openapi: 3.2.0
+info:
+  title: Pet API
+  version: '1.0'
+paths:
+  /pets:
+    get:
+      summary: List pets
+      parameters:
+        - name: q
+          in: querystring
+          content:
+            application/x-www-form-urlencoded:
+              schema:
+                type: object
+      responses:
+        '200':
+          description: OK

spec/openapi_parser/spec_validator/integration_3_2_spec.rb

@@ -206,4 +206,18 @@ def expect_clean(file)
       expect_clean('additional_operations_32.yaml')
     end
   end
+
+  describe 'Parameter in: querystring (3.2 addition)' do
+    it 'warns on the version-mismatched document under :warn' do
+      expect_mismatch_warns('querystring_31.yaml', [:querystring_before32])
+    end
+
+    it 'raises SpecViolationError on the version-mismatched document under :raise' do
+      expect_mismatch_raises('querystring_31.yaml', [:querystring_before32])
+    end
+
+    it 'stays clean on the correctly-versioned document' do
+      expect_clean('querystring_32.yaml')
+    end
+  end
 end

spec/openapi_parser/spec_validator/rules/querystring_before_32_spec.rb

@@ -0,0 +1,69 @@
+require_relative '../../../spec_helper'
+
+RSpec.describe 'OpenAPIParser::SpecValidator::Rules::QuerystringBefore32' do
+  def base_doc(openapi_version_string, param)
+    {
+      'openapi' => openapi_version_string,
+      'info' => { 'title' => 'test', 'version' => '1.0' },
+      'paths' => {
+        '/pets' => {
+          'get' => {
+            'parameters' => [param],
+            'responses' => { '200' => { 'description' => 'OK' } },
+          },
+        },
+      },
+    }
+  end
+
+  def doc_with(openapi_version_string)
+    OpenAPIParser.parse(base_doc(openapi_version_string, { 'name' => 'q', 'in' => 'querystring', 'content' => { 'application/x-www-form-urlencoded' => { 'schema' => { 'type' => 'object' } } } }), strict_reference_validation: false)
+  end
+
+  def doc_without(openapi_version_string)
+    OpenAPIParser.parse(base_doc(openapi_version_string, { 'name' => 'q', 'in' => 'query', 'schema' => { 'type' => 'string' } }), strict_reference_validation: false)
+  end
+
+  def run_rule_for(root)
+    OpenAPIParser::SpecValidator::Rules::QuerystringBefore32.new(root.openapi_version).check(root)
+  end
+
+  context 'with a 3.2 document using an in: querystring parameter' do
+    it 'reports no violation' do
+      expect(run_rule_for(doc_with('3.2.0'))).to eq []
+    end
+  end
+
+  context 'with a 3.2 document without an in: querystring parameter' do
+    it 'reports no violation' do
+      expect(run_rule_for(doc_without('3.2.0'))).to eq []
+    end
+  end
+
+  context 'with a 3.1 document using an in: querystring parameter' do
+    it 'reports one violation pointing at the field' do
+      violations = run_rule_for(doc_with('3.1.0'))
+      expect(violations.size).to eq 1
+      expect(violations.first.path).to eq '#/paths/~1pets/get/parameters/0/in'
+      expect(violations.first.rule_name).to eq :querystring_before32
+    end
+  end
+
+  context 'with a 3.1 document without an in: querystring parameter' do
+    it 'reports no violation' do
+      expect(run_rule_for(doc_without('3.1.0'))).to eq []
+    end
+  end
+
+  context 'with a 3.0 document using an in: querystring parameter' do
+    it 'reports one violation' do
+      expect(run_rule_for(doc_with('3.0.0')).size).to eq 1
+    end
+  end
+
+  context 'with a document whose openapi field is not a version' do
+    it 'reports no violation (rule skipped)' do
+      expect(run_rule_for(doc_with('not-a-version'))).to eq []
+    end
+  end
+end