rspec-openapi 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d55c7178770a58a980d06669adfab735ba84b51a283302dd8e14e91af4b7b4e9
-  data.tar.gz: 7b0030924262f8a1cd7027df612315b8d6e3fb89e91f9b4e57c3ec83f7e9bfd6
+  metadata.gz: 0a48ebba5d2201f35bb94f47d5bd649444bb9c58ae1f0ef91f57e315553f9ef2
+  data.tar.gz: 71d4dec68449c2e14b4d3ce7058622b7c56629bee2814e04b1f16e5e817a7bf2
 SHA512:
-  metadata.gz: 4cf846ca12d2062ae17c0b5d1829a7887c206425330c015f5fdde310c59678cb802b4cadb60f63c1ca6d55063c3d4f1cc2ac7813db10c6d8611a0fa3af975192
-  data.tar.gz: 7501fac5fbfd8b0c4cec6cb196feb9ff09a640c4aff7165a93a6880eebea194d5c30674eefadb53987538ebed913d8d43ab625f1a7c8a3a12ad76ba15b459687
+  metadata.gz: 4c984f5dbd1a4587a9d34686c50e06a832051215f5e22abc8a96781ecebe57e0bdddabeef093db06f5bea23f58e70322a7574168f621e8765721ab2c2cf19c48
+  data.tar.gz: 2877daab4753106d04275e3189b8a8e648b7268a6c6d7e422e94d5bfb230064a2e875e73531abe6930bfa6c8b7cdefe7d06ee512cdcb4e22adb618915349514b

data/.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    labels:
+      - "chore"

data/.github/workflows/codeql-analysis.yml

@@ -25,15 +25,15 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
+      uses: github/codeql-action/init@v3
       with:
         languages: ${{ matrix.language }}
         
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
+      uses: github/codeql-action/autobuild@v3
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
+      uses: github/codeql-action/analyze@v3

data/.github/workflows/rubocop.yml

@@ -14,7 +14,7 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
@@ -30,6 +30,6 @@ jobs:
         "
 
     - name: Upload Sarif output
-      uses: github/codeql-action/upload-sarif@v2
+      uses: github/codeql-action/upload-sarif@v3
       with:
         sarif_file: rubocop.sarif

data/.github/workflows/test.yml

@@ -26,14 +26,21 @@ jobs:
             rails: 6.1.6
           - ruby: ruby:3.1
             rails: 7.0.3
+          - ruby: ruby:3.3
+            rails: 7.1.2
             coverage: coverage
     env:
       RAILS_VERSION: ${{ matrix.rails == '' && '6.1.6' || matrix.rails }}
       COVERAGE: ${{ matrix.coverage || '' }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: bundle install
         run: bundle install -j$(nproc) --retry 3
+      - name: install simplecov-fork only for minitest with coverage
+        run: |
+          gem install specific_install
+          gem specific_install https://github.com/exoego/simplecov.git branch-fix
+        if: matrix.coverage == 'coverage'
       - run: bundle exec rspec
         timeout-minutes: 1
       - name: Upload coverage reports

data/.rubocop_todo.yml

@@ -1,25 +1,35 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2023-04-14 06:22:29 UTC using RuboCop version 1.49.0.
+# on 2024-01-13 11:12:43 UTC using RuboCop version 1.50.2.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 10
+# Offense count: 9
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
-  Max: 31
+  Max: 48
+
+# Offense count: 2
+# Configuration parameters: CountComments, CountAsOne.
+Metrics/ClassLength:
+  Max: 192
 
-# Offense count: 4
+# Offense count: 5
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:
-  Max: 10
+  Max: 13
 
-# Offense count: 13
+# Offense count: 16
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 30
+  Max: 31
+
+# Offense count: 1
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/PerceivedComplexity:
+  Max: 13
 
 # Offense count: 1
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
@@ -29,7 +39,7 @@ Naming/VariableNumber:
   Exclude:
     - 'spec/integration_tests/roda_test.rb'
 
-# Offense count: 5
+# Offense count: 6
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
   Exclude:

data/.simplecov_spawn.rb

@@ -9,6 +9,7 @@ unless ENV['COVERAGE'] && ENV['COVERAGE'].empty?
     SimpleCov::Formatter::CoberturaFormatter,
   ])
   SimpleCov.start do
+    enable_coverage :branch
     add_filter '/spec/'
     add_filter '/scripts/'
   end

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+## v0.11.0
+
+## What's Changed
+- feat: Allow path-based config overrides
+  [#162](https://github.com/exoego/rspec-openapi/pull/162)
+- enhancement: Sort HTTP methods, response status codes, and contents lexicographically
+  [#163](https://github.com/exoego/rspec-openapi/pull/163)
+- enhancement: Remove parameters that conflict with security schemas
+  [#166](https://github.com/exoego/rspec-openapi/pull/166)
+
+## v0.10.0
+- bugfix: Merge parameter data to preserve description in manually edited Openapi spec 
+  [#149](https://github.com/exoego/rspec-openapi/pull/149)
+- feat: Add ability to configure which path params to ignore
+  [#150](https://github.com/exoego/rspec-openapi/pull/150)
+- feat: Add custom title 
+  [#147](https://github.com/exoego/rspec-openapi/pull/147)
+- feat: Add ability to define custom summary and tags builders
+  [#148](https://github.com/exoego/rspec-openapi/pull/148)
+- enhancement: Sort paths lexicographically so the order of paths is more stable and predictable
+  [#155](https://github.com/exoego/rspec-openapi/pull/155)
+- enhancement: requestBody should not merge requestBody from error examples
+  [#154](https://github.com/exoego/rspec-openapi/pull/154)
+
 ## v0.9.0
 - bugfix: Fix engine path resolution
   [#113](https://github.com/exoego/rspec-openapi/pull/113)

data/Gemfile

@@ -10,7 +10,7 @@ gem 'roda'
 gem 'rspec-rails'
 
 group :test do
-  gem 'simplecov'
+  gem 'simplecov', git: 'https://github.com/exoego/simplecov.git', branch: 'branch-fix'
   gem 'simplecov-cobertura'
   gem 'super_diff'
 end

data/README.md

@@ -1,4 +1,4 @@
-# rspec-openapi ![test](https://github.com/exoego/rspec-openapi/workflows/test/badge.svg) [![codecov](https://codecov.io/gh/exoego/rspec-openapi/branch/master/graph/badge.svg?token=egYm6AlxkD)](https://codecov.io/gh/exoego/rspec-openapi)
+# rspec-openapi [![Gem Version](https://badge.fury.io/rb/rspec-openapi.svg)](https://badge.fury.io/rb/rspec-openapi) [![test](https://github.com/exoego/rspec-openapi/actions/workflows/test.yml/badge.svg)](https://github.com/exoego/rspec-openapi/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/exoego/rspec-openapi/branch/master/graph/badge.svg?token=egYm6AlxkD)](https://codecov.io/gh/exoego/rspec-openapi)
 
 Generate OpenAPI schema from RSpec request specs.
 
@@ -122,6 +122,8 @@ RSpec::OpenAPI.path = -> (example) {
   end
 }
 
+RSpec::OpenAPI.title = 'OpenAPI Documentation'
+
 # Disable generating `example`
 RSpec::OpenAPI.enable_example = false
 
@@ -167,8 +169,21 @@ EOS
 # Generate a custom description, given an RSpec example
 RSpec::OpenAPI.description_builder = -> (example) { example.description }
 
+# Generate a custom summary, given an RSpec example
+# This example uses the summary from the example_group.
+RSpec::OpenAPI.summary_builder = ->(example) { example.metadata.dig(:example_group, :openapi, :summary) }
+
+# Generate a custom tags, given an RSpec example
+# This example uses the tags from the parent_example_group
+RSpec::OpenAPI.tags_builder = -> (example) { example.metadata.dig(:example_group, :parent_example_group, :openapi, :tags) }
+
 # Change the example type(s) that will generate schema
 RSpec::OpenAPI.example_types = %i[request]
+
+# Configure which path params to ignore
+# :controller and :action always exist. :format is added when routes is configured as such.
+RSpec::OpenAPI.ignored_path_params = %i[controller action format]
+
 ```
 
 ### Can I use rspec-openapi with `$ref` to minimize duplication of schema?
@@ -199,7 +214,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/User"
-# Note) #/components/schamas is not needed to be defined.
+# Note) #/components/schemas is not needed to be defined.
 ```
 
 3. Then, re-run rspec-openapi. It will generate `#/components/schemas` with the referenced schema (`User` for example) newly-generated or updated.
@@ -278,7 +293,7 @@ If you find a room for improvement, open an issue.
 
 ### How can I add information which can't be generated from RSpec?
 
-rspec-openapi tries to keep manual modifications as much as possible when generating specs.
+rspec-openapi tries to preserve manual modifications as much as possible when generating specs.
 You can directly edit `doc/openapi.yaml` as you like without spoiling the automatic generation capability.
 
 ### Can I exclude specific specs from OpenAPI generation?

data/lib/rspec/openapi/record_builder.rb

@@ -62,8 +62,8 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
 
   def extract_request_attributes(request, example)
     metadata = example.metadata[:openapi] || {}
-    summary = metadata[:summary]
-    tags = metadata[:tags]
+    summary = metadata[:summary] || RSpec::OpenAPI.summary_builder.call(example)
+    tags = metadata[:tags] || RSpec::OpenAPI.tags_builder.call(example)
     operation_id = metadata[:operation_id]
     required_request_params = metadata[:required_request_params] || []
     security = metadata[:security]
@@ -83,7 +83,7 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
       tags ||= [route.requirements[:controller]&.classify].compact
       # :controller and :action always exist. :format is added when routes is configured as such.
       # TODO: Use .except(:controller, :action, :format) when we drop support for Ruby 2.x
-      raw_path_params = raw_path_params.slice(*(raw_path_params.keys - %i[controller action format]))
+      raw_path_params = raw_path_params.slice(*(raw_path_params.keys - RSpec::OpenAPI.ignored_path_params))
     end
     summary ||= "#{request.method} #{path}"
     [path, summary, tags, operation_id, required_request_params, raw_path_params, description, security]

data/lib/rspec/openapi/result_recorder.rb

@@ -7,25 +7,33 @@ class RSpec::OpenAPI::ResultRecorder
   end
 
   def record_results!
-    title = File.basename(Dir.pwd)
     @path_records.each do |path, records|
+      # Look for a path-specific config file and run it.
+      config_file = File.join(File.dirname(path), RSpec::OpenAPI.config_filename)
+      begin
+        require config_file if File.exist?(config_file)
+      rescue StandardError => e
+        puts "WARNING: Unable to load #{config_file}: #{e}"
+      end
+
+      title = RSpec::OpenAPI.title
       RSpec::OpenAPI::SchemaFile.new(path).edit do |spec|
         schema = RSpec::OpenAPI::DefaultSchema.build(title)
         schema[:info].merge!(RSpec::OpenAPI.info)
         RSpec::OpenAPI::SchemaMerger.merge!(spec, schema)
         new_from_zero = {}
         records.each do |record|
-          begin
-            record_schema = RSpec::OpenAPI::SchemaBuilder.build(record)
-            RSpec::OpenAPI::SchemaMerger.merge!(spec, record_schema)
-            RSpec::OpenAPI::SchemaMerger.merge!(new_from_zero, record_schema)
-          rescue StandardError, NotImplementedError => e # e.g. SchemaBuilder raises a NotImplementedError
-            @error_records[e] = record # Avoid failing the build
-          end
+          record_schema = RSpec::OpenAPI::SchemaBuilder.build(record)
+          RSpec::OpenAPI::SchemaMerger.merge!(spec, record_schema)
+          RSpec::OpenAPI::SchemaMerger.merge!(new_from_zero, record_schema)
+        rescue StandardError, NotImplementedError => e # e.g. SchemaBuilder raises a NotImplementedError
+          @error_records[e] = record # Avoid failing the build
         end
+        RSpec::OpenAPI::SchemaCleaner.cleanup_conflicting_security_parameters!(spec)
         RSpec::OpenAPI::SchemaCleaner.cleanup!(spec, new_from_zero)
         RSpec::OpenAPI::ComponentsUpdater.update!(spec, new_from_zero)
         RSpec::OpenAPI::SchemaCleaner.cleanup_empty_required_array!(spec)
+        RSpec::OpenAPI::SchemaSorter.deep_sort!(spec)
       end
     end
   end

data/lib/rspec/openapi/schema_builder.rb

@@ -120,6 +120,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
   def build_request_body(record)
     return nil if record.request_content_type.nil?
     return nil if record.request_params.empty?
+    return nil if record.status >= 400
 
     {
       content: {

data/lib/rspec/openapi/schema_cleaner.rb

@@ -39,6 +39,24 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
     base
   end
 
+  def cleanup_conflicting_security_parameters!(base)
+    security_schemes = base.dig('components', 'securitySchemes') || {}
+
+    return if security_schemes.empty?
+
+    paths_to_security_definitions = RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'paths', 'security')
+
+    paths_to_security_definitions.each do |path|
+      parent_path_definition = base.dig(*path.take(path.length - 1))
+
+      security_schemes.each do |security_scheme_name, security_scheme|
+        remove_parameters_conflicting_with_security_sceheme!(
+          parent_path_definition, security_scheme, security_scheme_name,
+        )
+      end
+    end
+  end
+
   def cleanup_empty_required_array!(base)
     paths_to_objects = [
       *RSpec::OpenAPI::HashHelper.matched_paths_deeply_nested(base, 'components.schemas', 'properties'),
@@ -53,6 +71,18 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
 
   private
 
+  def remove_parameters_conflicting_with_security_sceheme!(path_definition, security_scheme, security_scheme_name)
+    return unless path_definition['security']
+    return unless path_definition['parameters']
+    return unless path_definition.dig('security', 0).keys.include?(security_scheme_name)
+
+    path_definition['parameters'].reject! do |parameter|
+      parameter['in'] == security_scheme['in'] && # same location (ie. header)
+        parameter['name'] == security_scheme['name'] # same name (ie. AUTHORIZATION)
+    end
+    path_definition.delete('parameters') if path_definition['parameters'].empty?
+  end
+
   def cleanup_array!(base, spec, selector, fields_for_identity = [])
     marshal = lambda do |obj|
       Marshal.dump(slice(obj, fields_for_identity))

data/lib/rspec/openapi/schema_merger.rb

@@ -43,16 +43,28 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
   end
 
   def merge_arrays(base, key, value)
-    case key
-    when 'parameters'
-      base[key] = value | base[key]
-      base[key].uniq! { |param| param.slice('name', 'in') }
-    when 'required'
-      # Preserve properties that appears in all test cases
-      base[key] = value & base[key]
-    else
-      # last one wins
-      base[key] = value
+    base[key] = case key
+                when 'parameters'
+                  merge_parameters(base, key, value)
+                when 'required'
+                  # Preserve properties that appears in all test cases
+                  value & base[key]
+                else
+                  # last one wins
+                  value
+                end
+  end
+
+  def merge_parameters(base, key, value)
+    all_parameters = value | base[key]
+
+    unique_base_parameters = base[key].index_by { |parameter| [parameter['name'], parameter['in']] }
+    all_parameters = all_parameters.map do |parameter|
+      base_parameter = unique_base_parameters[[parameter['name'], parameter['in']]] || {}
+      base_parameter ? base_parameter.merge(parameter) : parameter
     end
+
+    all_parameters.uniq! { |param| param.slice('name', 'in') }
+    base[key] = all_parameters
   end
 end

data/lib/rspec/openapi/schema_sorter.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class << RSpec::OpenAPI::SchemaSorter = Object.new
+  # Sort some unpredictably ordered properties in a lexicographical manner to make the order more predictable.
+  #
+  # @param [Hash|Array]
+  def deep_sort!(spec)
+    # paths
+    deep_sort_by_selector!(spec, 'paths')
+
+    # methods
+    deep_sort_by_selector!(spec, 'paths.*')
+
+    # response status code
+    deep_sort_by_selector!(spec, 'paths.*.*.responses')
+
+    # content-type
+    deep_sort_by_selector!(spec, 'paths.*.*.responses.*.content')
+  end
+
+  private
+
+  # @param [Hash] base
+  # @param [String] selector
+  def deep_sort_by_selector!(base, selector)
+    RSpec::OpenAPI::HashHelper.matched_paths(base, selector).each do |paths|
+      deep_sort_hash!(base.dig(*paths))
+    end
+  end
+
+  def deep_sort_hash!(hash)
+    sorted = hash.entries.sort_by { |k, _| k }.to_h
+    hash.replace(sorted)
+  end
+end

data/lib/rspec/openapi/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module OpenAPI
-    VERSION = '0.9.0'
+    VERSION = '0.11.0'
   end
 end

data/lib/rspec/openapi.rb

@@ -9,15 +9,19 @@ require 'rspec/openapi/schema_builder'
 require 'rspec/openapi/schema_file'
 require 'rspec/openapi/schema_merger'
 require 'rspec/openapi/schema_cleaner'
+require 'rspec/openapi/schema_sorter'
 
 require 'rspec/openapi/minitest_hooks' if Object.const_defined?('Minitest')
 require 'rspec/openapi/rspec_hooks' if ENV['OPENAPI'] && Object.const_defined?('RSpec')
 
 module RSpec::OpenAPI
   @path = 'doc/openapi.yaml'
+  @title = File.basename(Dir.pwd)
   @comment = nil
   @enable_example = true
   @description_builder = ->(example) { example.description }
+  @summary_builder = ->(example) { example.metadata[:summary] }
+  @tags_builder = ->(example) { example.metadata[:tags] }
   @info = {}
   @application_version = '1.0.0'
   @request_headers = []
@@ -26,12 +30,19 @@ module RSpec::OpenAPI
   @example_types = %i[request]
   @response_headers = []
   @path_records = Hash.new { |h, k| h[k] = [] }
+  @ignored_path_params = %i[controller action format]
+
+  # This is the configuraion override file name we look for within each path.
+  @config_filename = 'rspec_openapi.rb'
 
   class << self
     attr_accessor :path,
+                  :title,
                   :comment,
                   :enable_example,
                   :description_builder,
+                  :summary_builder,
+                  :tags_builder,
                   :info,
                   :application_version,
                   :request_headers,
@@ -39,6 +50,9 @@ module RSpec::OpenAPI
                   :security_schemes,
                   :example_types,
                   :response_headers,
-                  :path_records
+                  :path_records,
+                  :ignored_path_params
+
+    attr_reader   :config_filename
   end
 end

data/scripts/rspec_with_simplecov

@@ -36,8 +36,7 @@ begin
     require 'simplecov'
 
     SimpleCov.start do
-      # Flaky :(
-      # enable_coverage :branch
+      enable_coverage :branch
     end
   end
 rescue LoadError

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-openapi
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Takashi Kokubun
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-10 00:00:00.000000000 Z
+date: 2024-01-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -47,6 +47,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/dependabot.yml"
 - ".github/workflows/codeql-analysis.yml"
 - ".github/workflows/rubocop.yml"
 - ".github/workflows/test.yml"
@@ -75,6 +76,7 @@ files:
 - lib/rspec/openapi/schema_cleaner.rb
 - lib/rspec/openapi/schema_file.rb
 - lib/rspec/openapi/schema_merger.rb
+- lib/rspec/openapi/schema_sorter.rb
 - lib/rspec/openapi/version.rb
 - rspec-openapi.gemspec
 - scripts/rspec