Add support for parameter format specification in schema building (#254)

Author: krzyzak

README.md

@@ -188,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]
 

lib/rspec/openapi.rb

@@ -33,6 +33,7 @@ def load_environment_settings
   @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 @@ class << self
                   :description_builder,
                   :summary_builder,
                   :tags_builder,
+                  :formats_builder,
                   :info,
                   :application_version,
                   :request_headers,

lib/rspec/openapi/extractors/hanami.rb

@@ -59,6 +59,7 @@ def request_attributes(request, example)
     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 @@ def request_attributes(request, example)
 
     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

lib/rspec/openapi/extractors/rack.rb

@@ -9,6 +9,7 @@ def request_attributes(request, example)
     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 @@ def request_attributes(request, example)
     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

lib/rspec/openapi/extractors/rails.rb

@@ -19,6 +19,8 @@ def request_attributes(request, example)
     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 @@ def request_attributes(request, example)
 
     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

lib/rspec/openapi/record.rb

@@ -12,6 +12,7 @@
   :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: []}]

lib/rspec/openapi/record_builder.rb

@@ -12,7 +12,7 @@ def build(context, example:, extractor:)
     return if request.nil?
 
     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 =
+    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) }
@@ -31,6 +31,7 @@ def build(context, example:, extractor:)
       request_headers: request_headers,
       summary: summary,
       tags: tags,
+      formats: formats,
       operation_id: operation_id,
       description: description,
       security: security,

lib/rspec/openapi/schema_builder.rb

@@ -18,7 +18,7 @@ def build(record)
       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,
         }
@@ -73,7 +73,7 @@ def build_parameters(record)
         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
@@ -83,7 +83,7 @@ def build_parameters(record)
         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
@@ -93,7 +93,7 @@ def build_parameters(record)
         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
@@ -110,7 +110,7 @@ def build_response_headers(record)
 
     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
 
@@ -134,36 +134,38 @@ def build_request_body(record)
     {
       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)
     end
     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
@@ -187,6 +189,12 @@ def build_type(value, disposition)
     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)

spec/apps/rails/doc/openapi.json

@@ -659,10 +659,12 @@
                         "format": "float"
                       },
                       "created_at": {
-                        "type": "string"
+                        "type": "string",
+                        "format": "date-time"
                       },
                       "updated_at": {
-                        "type": "string"
+                        "type": "string",
+                        "format": "date-time"
                       }
                     },
                     "required": [
@@ -763,10 +765,12 @@
                       "format": "float"
                     },
                     "created_at": {
-                      "type": "string"
+                      "type": "string",
+                      "format": "date-time"
                     },
                     "updated_at": {
-                      "type": "string"
+                      "type": "string",
+                      "format": "date-time"
                     }
                   },
                   "required": [
@@ -907,10 +911,12 @@
                       "format": "float"
                     },
                     "created_at": {
-                      "type": "string"
+                      "type": "string",
+                      "format": "date-time"
                     },
                     "updated_at": {
-                      "type": "string"
+                      "type": "string",
+                      "format": "date-time"
                     }
                   },
                   "required": [
@@ -1001,10 +1007,12 @@
                       "format": "float"
                     },
                     "created_at": {
-                      "type": "string"
+                      "type": "string",
+                      "format": "date-time"
                     },
                     "updated_at": {
-                      "type": "string"
+                      "type": "string",
+                      "format": "date-time"
                     }
                   },
                   "required": [
@@ -1154,10 +1162,12 @@
                       "format": "float"
                     },
                     "created_at": {
-                      "type": "string"
+                      "type": "string",
+                      "format": "date-time"
                     },
                     "updated_at": {
-                      "type": "string"
+                      "type": "string",
+                      "format": "date-time"
                     }
                   },
                   "required": [

spec/apps/rails/doc/openapi.yaml

@@ -416,8 +416,10 @@ paths:
                       format: float
                     created_at:
                       type: string
+                      format: date-time
                     updated_at:
                       type: string
+                      format: date-time
                   required:
                   - id
                   - name
@@ -486,8 +488,10 @@ paths:
                     format: float
                   created_at:
                     type: string
+                    format: date-time
                   updated_at:
                     type: string
+                    format: date-time
                 required:
                 - id
                 - name
@@ -584,8 +588,10 @@ paths:
                     format: float
                   created_at:
                     type: string
+                    format: date-time
                   updated_at:
                     type: string
+                    format: date-time
                 required:
                 - id
                 - name
@@ -650,8 +656,10 @@ paths:
                     format: float
                   created_at:
                     type: string
+                    format: date-time
                   updated_at:
                     type: string
+                    format: date-time
                 required:
                 - id
                 - name
@@ -752,8 +760,10 @@ paths:
                     format: float
                   created_at:
                     type: string
+                    format: date-time
                   updated_at:
                     type: string
+                    format: date-time
                 required:
                 - id
                 - name