rspec-openapi 0.18.3 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39da96c0f0b1650e0504d45a624be7905c9f47a2b128e992eecb5b05b828dd87
-  data.tar.gz: 5c6cb0fdaf3900ae93d0618c82b6762c8cf50002e7ac155c23a46b543f91d126
+  metadata.gz: f0fd8968099cf455a6ee1eabe6039c60955020493d97e584fb57b1ba79aca8d3
+  data.tar.gz: 15ae08318ba0843a65cbd4bf418b82f2ce9d7c173600f0ea2d776763f4790819
 SHA512:
-  metadata.gz: df87ce7e2b08623ec314330020d011ede771872a435f11b266be1f1c1a2e24c8329559b1f3e42b50a58a86c442c0afed2e98444694138823b9b17ebb94e54878
-  data.tar.gz: c89fb952a0d8fbc4c5ed814bd11513d2323f2c5237ad0a7b0e341e2522c329a331230b51ecab3bcf42a60dd4e5da090a337202dac37db3d4f68ab82ad7a9f91b
+  metadata.gz: 2c15dc4a7d63f610cd654ea2718ffccbd15c59ec66bcc45f219352bdccbe7a6e49baa4810a866fefd483b34ec94992a7f48ce799d8cace7ced59f2dd5fb9db81
+  data.tar.gz: 9306ae8e95e9d4dcb0aa40d20b716217c2712ad081448c7f61cb832dd210864883c6f93999257715347fd85b5eb9f1d5ccb0615db3102de112fdfddebeb78318

data/.github/workflows/test.yml

@@ -25,6 +25,8 @@ jobs:
             rails: 7.0.8
           - ruby: ruby:3.3
             rails: 7.1.3.2
+          - ruby: ruby:3.4
+            rails: 8.0.2
             coverage: coverage
     env:
       RAILS_VERSION: ${{ matrix.rails == '' && '6.1.6' || matrix.rails }}
@@ -38,7 +40,7 @@ jobs:
       - run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
         name: codecov-action@v4 workaround
       - name: Upload coverage reports
-        uses: codecov/codecov-action@v4
+        uses: codecov/codecov-action@v5
         if: matrix.coverage == 'coverage'
         with:
           fail_ci_if_error: true

data/Gemfile

@@ -11,8 +11,12 @@ if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.0.0')
   gem 'hanami', ENV['HANAMI_VERSION'] || '2.1.0'
   gem 'hanami-controller', ENV['HANAMI_VERSION'] || '2.1.0'
   gem 'hanami-router', ENV['HANAMI_VERSION'] || '2.1.0'
+
+  gem 'dry-logger', '1.0.3'
 end
 
+gem 'concurrent-ruby', '1.3.4'
+
 gem 'roda'
 
 gem 'rails-dom-testing', '~> 2.2'

data/README.md

@@ -1,4 +1,5 @@
-# rspec-openapi [![Gem Version](https://badge.fury.io/rb/rspec-openapi.svg)](https://rubygems.org/gems/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) [![Ruby-toolbox](https://img.shields.io/badge/ruby-toolbox-a61414?cacheSeconds=31536000)](https://www.ruby-toolbox.com/projects/rspec-openapi)
+# rspec-openapi [![Gem Version](https://badge.fury.io/rb/rspec-openapi.svg)](https://rubygems.org/gems/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) [![Ruby-toolbox](https://img.shields.io/badge/ruby-toolbox-a61414?cacheSeconds=31536000)](https://www.ruby-toolbox.com/projects/rspec-openapi) [![DeepWiki](https://img.shields.io/badge/See_on-DeepWiki-blue)](https://deepwiki.com/exoego/rspec-openapi)
+
 
 Generate OpenAPI schema from RSpec request specs.
 
@@ -52,7 +53,7 @@ end
 If you run the spec with `OPENAPI=1`,
 
 ```
-OPENAPI=1 rspec spec/requests/tables_spec.rb
+OPENAPI=1 bundle exec rspec spec/requests/tables_spec.rb
 ```
 
 It will generate [`doc/openapi.yaml` file](./spec/rails/doc/openapi.yaml) like:
@@ -122,8 +123,18 @@ RSpec::OpenAPI.path = -> (example) {
   end
 }
 
+# Change the default title of the generated schema
 RSpec::OpenAPI.title = 'OpenAPI Documentation'
 
+# Or generate individual titles for your partial schema files, given an RSpec example
+RSpec::OpenAPI.title = -> (example) {
+  case example.file_path
+  when %r[spec/requests/api/v1/] then 'API v1 Documentation'
+  when %r[spec/requests/api/v2/] then 'API v2 Documentation'
+  else 'OpenAPI Documentation'
+  end
+}
+
 # Disable generating `example`
 RSpec::OpenAPI.enable_example = false
 
@@ -177,6 +188,10 @@ RSpec::OpenAPI.summary_builder = ->(example) { example.metadata.dig(:example_gro
 # 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) }
 
+# Configure custom format for specific properties
+# This example assigns 'date-time' format to properties with names ending in '_at'
+RSpec::OpenAPI.formats_builder = ->(_example, key) { key.end_with?('_at') ? 'date-time' : nil }
+
 # Change the example type(s) that will generate schema
 RSpec::OpenAPI.example_types = %i[request]
 

data/lib/rspec/openapi/extractors/hanami.rb

@@ -59,6 +59,7 @@ class << RSpec::OpenAPI::Extractors::Hanami = Object.new
     metadata = example.metadata[:openapi] || {}
     summary = metadata[:summary] || RSpec::OpenAPI.summary_builder.call(example)
     tags = metadata[:tags] || RSpec::OpenAPI.tags_builder.call(example)
+    formats = metadata[:formats] || RSpec::OpenAPI.formats_builder.curry.call(example)
     operation_id = metadata[:operation_id]
     required_request_params = metadata[:required_request_params] || []
     security = metadata[:security]
@@ -76,7 +77,18 @@ class << RSpec::OpenAPI::Extractors::Hanami = Object.new
 
     raw_path_params = raw_path_params.slice(*(raw_path_params.keys - RSpec::OpenAPI.ignored_path_params))
 
-    [path, summary, tags, operation_id, required_request_params, raw_path_params, description, security, deprecated]
+    [
+      path,
+      summary,
+      tags,
+      operation_id,
+      required_request_params,
+      raw_path_params,
+      description,
+      security,
+      deprecated,
+      formats,
+    ]
   end
 
   # @param [RSpec::ExampleGroups::*] context

data/lib/rspec/openapi/extractors/rack.rb

@@ -9,6 +9,7 @@ class << RSpec::OpenAPI::Extractors::Rack = Object.new
     metadata = example.metadata[:openapi] || {}
     summary = metadata[:summary] || RSpec::OpenAPI.summary_builder.call(example)
     tags = metadata[:tags] || RSpec::OpenAPI.tags_builder.call(example)
+    formats = metadata[:formats] || RSpec::OpenAPI.formats_builder.curry.call(example)
     operation_id = metadata[:operation_id]
     required_request_params = metadata[:required_request_params] || []
     security = metadata[:security]
@@ -17,7 +18,18 @@ class << RSpec::OpenAPI::Extractors::Rack = Object.new
     raw_path_params = request.path_parameters
     path = request.path
     summary ||= "#{request.method} #{path}"
-    [path, summary, tags, operation_id, required_request_params, raw_path_params, description, security, deprecated]
+    [
+      path,
+      summary,
+      tags,
+      operation_id,
+      required_request_params,
+      raw_path_params,
+      description,
+      security,
+      deprecated,
+      formats,
+    ]
   end
 
   # @param [RSpec::ExampleGroups::*] context

data/lib/rspec/openapi/extractors/rails.rb

@@ -12,13 +12,15 @@ class << RSpec::OpenAPI::Extractors::Rails = Object.new
 
     route, path = find_rails_route(fixed_request)
 
-    raise "No route matched for #{fixed_request.request_method} #{fixed_request.path_info}" if route.nil?
-
     return RSpec::OpenAPI::Extractors::Rack.request_attributes(request, example) unless path
 
+    raise "No route matched for #{fixed_request.request_method} #{fixed_request.path_info}" if route.nil?
+
     metadata = example.metadata[:openapi] || {}
     summary = metadata[:summary] || RSpec::OpenAPI.summary_builder.call(example)
     tags = metadata[:tags] || RSpec::OpenAPI.tags_builder.call(example)
+    formats = metadata[:formats] || RSpec::OpenAPI.formats_builder.curry.call(example)
+
     operation_id = metadata[:operation_id]
     required_request_params = metadata[:required_request_params] || []
     security = metadata[:security]
@@ -34,7 +36,18 @@ class << RSpec::OpenAPI::Extractors::Rails = Object.new
 
     summary ||= "#{request.method} #{path}"
 
-    [path, summary, tags, operation_id, required_request_params, raw_path_params, description, security, deprecated]
+    [
+      path,
+      summary,
+      tags,
+      operation_id,
+      required_request_params,
+      raw_path_params,
+      description,
+      security,
+      deprecated,
+      formats,
+    ]
   end
 
   # @param [RSpec::ExampleGroups::*] context

data/lib/rspec/openapi/record.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 RSpec::OpenAPI::Record = Struct.new(
+  :title,                 # @param [String]  - "API Documentation - Statuses"
   :http_method,           # @param [String]  - "GET"
   :path,                  # @param [String]  - "/v1/status/:id"
   :path_params,           # @param [Hash]    - {:controller=>"v1/statuses", :action=>"create", :id=>"1"}
@@ -11,6 +12,7 @@ RSpec::OpenAPI::Record = Struct.new(
   :request_headers,       # @param [Array]  - [["header_key1", "header_value1"], ["header_key2", "header_value2"]]
   :summary,               # @param [String]  - "v1/statuses #show"
   :tags,                  # @param [Array]   - ["Status"]
+  :formats,               # @param [Proc]    - ->(key) { key.end_with?('_at') ? 'date-time' : nil }
   :operation_id,          # @param [String]   - "request-1234"
   :description,           # @param [String]  - "returns a status"
   :security,              # @param [Array]  - [{securityScheme1: []}]

data/lib/rspec/openapi/record_builder.rb

@@ -11,7 +11,8 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
     request, response = extractor.request_response(context)
     return if request.nil?
 
-    path, summary, tags, operation_id, required_request_params, raw_path_params, description, security, deprecated =
+    title = RSpec::OpenAPI.title.then { |t| t.is_a?(Proc) ? t.call(example) : t }
+    path, summary, tags, operation_id, required_request_params, raw_path_params, description, security, deprecated, formats =
       extractor.request_attributes(request, example)
 
     return if RSpec::OpenAPI.ignored_paths.any? { |ignored_path| path.match?(ignored_path) }
@@ -19,6 +20,7 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
     request_headers, response_headers = extract_headers(request, response)
 
     RSpec::OpenAPI::Record.new(
+      title: title,
       http_method: request.method,
       path: path,
       path_params: raw_path_params,
@@ -29,6 +31,7 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
       request_headers: request_headers,
       summary: summary,
       tags: tags,
+      formats: formats,
       operation_id: operation_id,
       description: description,
       security: security,

data/lib/rspec/openapi/result_recorder.rb

@@ -16,7 +16,7 @@ class RSpec::OpenAPI::ResultRecorder
         puts "WARNING: Unable to load #{config_file}: #{e}"
       end
 
-      title = RSpec::OpenAPI.title
+      title = records.first.title
       RSpec::OpenAPI::SchemaFile.new(path).edit do |spec|
         schema = RSpec::OpenAPI::DefaultSchema.build(title)
         schema[:info].merge!(RSpec::OpenAPI.info)

data/lib/rspec/openapi/schema_builder.rb

@@ -18,7 +18,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
       if has_content
         response[:content] = {
           normalize_content_type(record.response_content_type) => {
-            schema: build_property(record.response_body, disposition: disposition),
+            schema: build_property(record.response_body, disposition: disposition, record: record),
             example: response_example(record, disposition: disposition),
           }.compact,
         }
@@ -36,7 +36,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
             security: record.security,
             deprecated: record.deprecated ? true : nil,
             parameters: build_parameters(record),
-            requestBody: http_method == 'get' ? nil : build_request_body(record),
+            requestBody: include_nil_request_body?(http_method) ? nil : build_request_body(record),
             responses: {
               record.status.to_s => response,
             },
@@ -48,6 +48,10 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
 
   private
 
+  def include_nil_request_body?(http_method)
+    %w[delete get].include?(http_method)
+  end
+
   def enrich_with_required_keys(obj)
     obj[:required] = obj[:properties]&.keys || []
     obj
@@ -69,7 +73,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
         name: build_parameter_name(key, value),
         in: 'path',
         required: true,
-        schema: build_property(try_cast(value)),
+        schema: build_property(try_cast(value), key: key, record: record),
         example: (try_cast(value) if example_enabled?),
       }.compact
     end
@@ -79,7 +83,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
         name: build_parameter_name(key, value),
         in: 'query',
         required: record.required_request_params.include?(key),
-        schema: build_property(try_cast(value)),
+        schema: build_property(try_cast(value), key: key, record: record),
         example: (try_cast(value) if example_enabled?),
       }.compact
     end
@@ -89,7 +93,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
         name: build_parameter_name(key, value),
         in: 'header',
         required: true,
-        schema: build_property(try_cast(value)),
+        schema: build_property(try_cast(value), key: key, record: record),
         example: (try_cast(value) if example_enabled?),
       }.compact
     end
@@ -106,7 +110,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
 
     record.response_headers.each do |key, value|
       headers[key] = {
-        schema: build_property(try_cast(value)),
+        schema: build_property(try_cast(value), key: key, record: record),
       }.compact
     end
 
@@ -130,27 +134,29 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
     {
       content: {
         normalize_content_type(record.request_content_type) => {
-          schema: build_property(record.request_params),
+          schema: build_property(record.request_params, record: record),
           example: (build_example(record.request_params) if example_enabled?),
         }.compact,
       },
     }
   end
 
-  def build_property(value, disposition: nil)
-    property = build_type(value, disposition)
+  def build_property(value, disposition: nil, key: nil, record: nil)
+    format = disposition ? 'binary' : infer_format(key, record)
+
+    property = build_type(value, format: format)
 
     case value
     when Array
       property[:items] = if value.empty?
                            {} # unknown
                          else
-                           build_property(value.first)
+                           build_property(value.first, record: record)
                          end
     when Hash
       property[:properties] = {}.tap do |properties|
         value.each do |key, v|
-          properties[key] = build_property(v)
+          properties[key] = build_property(v, record: record, key: key)
         end
       end
       property = enrich_with_required_keys(property)
@@ -158,8 +164,8 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
     property
   end
 
-  def build_type(value, disposition)
-    return { type: 'string', format: 'binary' } if disposition
+  def build_type(value, format: nil)
+    return { type: 'string', format: format } if format
 
     case value
     when String
@@ -183,6 +189,12 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
     end
   end
 
+  def infer_format(key, record)
+    return nil if !key || !record || !record.formats
+
+    record.formats[key]
+  end
+
   # Convert an always-String param to an appropriate type
   def try_cast(value)
     Integer(value)

data/lib/rspec/openapi/schema_cleaner.rb

@@ -50,7 +50,7 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
       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!(
+        remove_parameters_conflicting_with_security_scheme!(
           parent_path_definition, security_scheme, security_scheme_name,
         )
       end
@@ -71,7 +71,7 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
 
   private
 
-  def remove_parameters_conflicting_with_security_sceheme!(path_definition, security_scheme, security_scheme_name)
+  def remove_parameters_conflicting_with_security_scheme!(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)

data/lib/rspec/openapi/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module OpenAPI
-    VERSION = '0.18.3'
+    VERSION = '0.19.0'
   end
 end

data/lib/rspec/openapi.rb

@@ -33,6 +33,7 @@ module RSpec::OpenAPI
   @description_builder = ->(example) { example.description }
   @summary_builder = ->(example) { example.metadata[:summary] }
   @tags_builder = ->(example) { example.metadata[:tags] }
+  @formats_builder = ->(example) { example.metadata[:formats] }
   @info = {}
   @application_version = '1.0.0'
   @request_headers = []
@@ -56,6 +57,7 @@ module RSpec::OpenAPI
                   :description_builder,
                   :summary_builder,
                   :tags_builder,
+                  :formats_builder,
                   :info,
                   :application_version,
                   :request_headers,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-openapi
 version: !ruby/object:Gem::Version
-  version: 0.18.3
+  version: 0.19.0
 platform: ruby
 authors:
 - Takashi Kokubun
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-05-01 00:00:00.000000000 Z
+date: 2025-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -109,7 +109,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/exoego/rspec-openapi
   source_code_uri: https://github.com/exoego/rspec-openapi
-  changelog_uri: https://github.com/exoego/rspec-openapi/releases/tag/v0.18.3
+  changelog_uri: https://github.com/exoego/rspec-openapi/releases/tag/v0.19.0
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -126,7 +126,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Generate OpenAPI schema from RSpec request specs