rspec-openapi 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9529f01aae2b2d1c77050b4a01f299c77a285057aa6fc7088a69ee7d2638e61
-  data.tar.gz: ca00d5561aaa0faeaadc1d42e7d2a25f729567b21af001c9677675e3738ae195
+  metadata.gz: 0ce13b09ac314ce43bb224b5c8ff1260f283f2a415032418c3908ac51a4a6b8b
+  data.tar.gz: dc9aaa1fe4d3f1228bed06e37cf1b26e87e045b3666b244514587204b31a8b78
 SHA512:
-  metadata.gz: 5de0ee281ad93e679c8f5456769fc1569f51ebfe5408c884d7061f9c802e3f8578ad48799a71306a6ce7cf0aa76959b2e30e2c97956e98237d08745c13d7aa54
-  data.tar.gz: 0a0076cedb0633762235833ead555db74720fad22c9f03fa84a7cdeaba617a823117a508c5acdd2e518ac1660582849c94ab68ccaed629e8f109ecfefe64227c
+  metadata.gz: 37d15147e73665c3dd236e971623a4a7a2feafeb08042191d42952e2b46a0526617bdbce87b2294d62856fc96730a92cee538bd408ea8218190ec8d90c7a151f
+  data.tar.gz: 209e5b659ccaa36c63673314172f1d05e67d1a3d879afb2cb5907d12500dc2fa18c52c42bfc9cb0193d0e4c13a85649f9930b91e52339a5ffa900183aa400be3

data/README.md

@@ -137,9 +137,12 @@ RSpec::OpenAPI.info = {
   }
 }
 
-# Set `headers` - generate parameters with headers for a request
+# Set request `headers` - generate parameters with headers for a request
 RSpec::OpenAPI.request_headers = %w[X-Authorization-Token]
 
+# Set response `headers` - generate parameters with headers for a response
+RSpec::OpenAPI.response_headers = %w[X-Cursor]
+
 # Set `servers` - generate servers of a schema file
 RSpec::OpenAPI.servers = [{ url: 'http://localhost:3000' }]
 
@@ -158,6 +161,111 @@ RSpec::OpenAPI.description_builder = -> (example) { example.description }
 RSpec::OpenAPI.example_types = %i[request]
 ```
 
+### Can I use rspec-openapi with `$ref` to minimize duplication of schema?
+
+Yes, rspec-openapi v0.7.0+ supports [`$ref` mechanism](https://swagger.io/docs/specification/using-ref/) and generates
+schemas under `#/components/schemas` with some manual steps.
+
+1. First, generate plain OpenAPI file.
+2. Then, manually replace the duplications with `$ref`.
+
+```yaml
+paths:
+  "/users":
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/User"
+  "/users/{id}":
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/User"
+# Note) #/components/schamas 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.
+
+```yaml
+paths:
+  "/users":
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/User"
+  "/users/{id}":
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/User"
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        role:
+          type: array
+          items:
+            type: string
+```
+
+rspec-openapi also supports `$ref` in `properties` of schemas. Example)
+
+```yaml
+paths:
+  "/locations":
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Location"
+components:
+  schemas:
+    Location:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        Coordinate:
+          "$ref": "#/components/schemas/Coordinate"
+    Coordinate:
+      type: object
+      properties:
+        lat:
+          type: string
+        lon:
+          type: string
+```
+
+Note that automatic `schemas` update feature is still new and may not work in complex scenario.
+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.

data/lib/rspec/openapi/components_updater.rb

@@ -0,0 +1,65 @@
+require_relative 'hash_helper'
+
+class << RSpec::OpenAPI::ComponentsUpdater = Object.new
+  # @param [Hash] base
+  # @param [Hash] fresh
+  def update!(base, fresh)
+    # Top-level schema: Used as the body of request or response
+    top_level_refs = paths_to_top_level_refs(base)
+    return if top_level_refs.empty?
+    fresh_schemas = build_fresh_schemas(top_level_refs, base, fresh)
+
+    # Nested schema: References in Top-level schemas. May contain some top-level schema.
+    generated_schema_names = fresh_schemas.keys
+    nested_refs = find_non_top_level_nested_refs(base, generated_schema_names)
+    nested_refs.each do |paths|
+      parent_name = paths[-4]
+      property_name = paths[-2]
+      nested_schema = fresh_schemas.dig(parent_name, 'properties', property_name)
+
+      # Skip if the property using $ref is not found in the parent schema. The property may be removed.
+      next if nested_schema.nil?
+
+      schema_name = base.dig(*paths)&.gsub('#/components/schemas/', '')
+      fresh_schemas[schema_name] ||= {}
+      RSpec::OpenAPI::SchemaMerger.merge!(fresh_schemas[schema_name], nested_schema)
+    end
+
+    RSpec::OpenAPI::SchemaMerger.merge!(base, { 'components' => { 'schemas' => fresh_schemas }})
+    RSpec::OpenAPI::SchemaCleaner.cleanup_components_schemas!(base, { 'components' => { 'schemas' => fresh_schemas } })
+  end
+
+  private
+
+  def build_fresh_schemas(references, base, fresh)
+    references.inject({}) do |acc, paths|
+      ref_link = dig_schema(base, paths).dig('$ref')
+      schema_name = ref_link.gsub('#/components/schemas/', '')
+      schema_body = dig_schema(fresh, paths)
+      RSpec::OpenAPI::SchemaMerger.merge!(acc, { schema_name => schema_body })
+    end
+  end
+
+  def dig_schema(obj, paths)
+    obj.dig(*paths, 'schema', 'items') || obj.dig(*paths, 'schema')
+  end
+
+  def paths_to_top_level_refs(base)
+    request_bodies = RSpec::OpenAPI::HashHelper::matched_paths(base, 'paths.*.*.requestBody.content.application/json')
+    responses = RSpec::OpenAPI::HashHelper::matched_paths(base, 'paths.*.*.responses.*.content.application/json')
+    (request_bodies + responses).select do |paths|
+      dig_schema(base, paths)&.dig('$ref')&.start_with?('#/components/schemas/')
+    end
+  end
+
+  def find_non_top_level_nested_refs(base, generated_names)
+    nested_refs = RSpec::OpenAPI::HashHelper::matched_paths(base, 'components.schemas.*.properties.*.$ref')
+
+    # Reject already-generated schemas to reduce unnecessary loop
+    nested_refs.reject do |paths|
+      ref_link = base.dig(*paths)
+      schema_name = ref_link.gsub('#/components/schemas/', '')
+      generated_names.include?(schema_name)
+    end
+  end
+end

data/lib/rspec/openapi/hash_helper.rb

@@ -0,0 +1,23 @@
+class << RSpec::OpenAPI::HashHelper = Object.new
+  def paths_to_all_fields(obj)
+    case obj
+    when Hash
+      obj.each.flat_map do |k, v|
+        k = k.to_s
+        [[k]] + paths_to_all_fields(v).map { |x| [k, *x] }
+      end
+    else
+      []
+    end
+  end
+
+  def matched_paths(obj, selector)
+    selector_parts = selector.split('.').map(&:to_s)
+    selectors = paths_to_all_fields(obj).select do |key_parts|
+      key_parts.size == selector_parts.size && key_parts.zip(selector_parts).all? do |kp, sp|
+        kp == sp || (sp == '*' && kp != nil)
+      end
+    end
+    selectors
+  end
+end

data/lib/rspec/openapi/hooks.rb

@@ -1,9 +1,11 @@
 require 'rspec'
+require 'rspec/openapi/components_updater'
 require 'rspec/openapi/default_schema'
 require 'rspec/openapi/record_builder'
 require 'rspec/openapi/schema_builder'
 require 'rspec/openapi/schema_file'
 require 'rspec/openapi/schema_merger'
+require 'rspec/openapi/schema_cleaner'
 
 path_records = Hash.new { |h, k| h[k] = [] }
 error_records = {}
@@ -23,13 +25,18 @@ RSpec.configuration.after(:suite) do
       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
-          RSpec::OpenAPI::SchemaMerger.merge!(spec, RSpec::OpenAPI::SchemaBuilder.build(record))
+          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
       end
+      RSpec::OpenAPI::SchemaCleaner.cleanup!(spec, new_from_zero)
+      RSpec::OpenAPI::ComponentsUpdater.update!(spec, new_from_zero)
     end
   end
   if error_records.any?

data/lib/rspec/openapi/record.rb

@@ -11,6 +11,7 @@ RSpec::OpenAPI::Record = Struct.new(
   :description,           # @param [String]  - "returns a status"
   :status,                # @param [Integer] - 200
   :response_body,         # @param [Object]  - {"status" => "ok"}
+  :response_headers,      # @param [Array]  - [["header_key1", "header_value1"], ["header_key2", "header_value2"]]
   :response_content_type, # @param [String]  - "application/json"
   :response_content_disposition, # @param [String]  - "inline"
   keyword_init: true,

data/lib/rspec/openapi/record_builder.rb

@@ -42,6 +42,12 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
 
     metadata_options = example.metadata[:openapi] || {}
 
+    response_headers = RSpec::OpenAPI.response_headers.each_with_object([]) do |header, headers_arr|
+      header_key = header
+      header_value = response.headers[header_key]
+      headers_arr << [header_key, header_value] if header_value
+    end
+
     RSpec::OpenAPI::Record.new(
       method: request.request_method,
       path: path,
@@ -55,6 +61,7 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
       description: metadata_options[:description] || RSpec::OpenAPI.description_builder.call(example),
       status: response.status,
       response_body: response_body,
+      response_headers: response_headers,
       response_content_type: response.media_type,
       response_content_disposition: response.header["Content-Disposition"],
     ).freeze

data/lib/rspec/openapi/schema_builder.rb

@@ -6,6 +6,9 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
       description: record.description,
     }
 
+    response_headers = build_response_headers(record)
+    response[:headers] = response_headers unless response_headers.empty?
+
     if record.response_body
       disposition = normalize_content_disposition(record.response_content_disposition)
       response[:content] = {
@@ -81,6 +84,18 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
     parameters
   end
 
+  def build_response_headers(record)
+    headers = {}
+
+    record.response_headers.each do |key, value|
+      headers[key] = {
+        schema: build_property(try_cast(value)),
+      }.compact
+    end
+
+    headers
+  end
+
   def build_parameter_name(key, value)
     key = key.to_s
     if value.is_a?(Hash) && (value_keys = value.keys).size == 1
@@ -110,7 +125,11 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
 
     case value
     when Array
-      property[:items] = build_property(value.first)
+      if value.empty?
+        property[:items] = {} # unknown
+      else
+        property[:items] = build_property(value.first)
+      end
     when Hash
       property[:properties] = {}.tap do |properties|
         value.each do |key, v|

data/lib/rspec/openapi/schema_cleaner.rb

@@ -0,0 +1,86 @@
+# For Ruby 3.0+
+require 'set'
+
+require_relative 'hash_helper'
+
+class << RSpec::OpenAPI::SchemaCleaner = Object.new
+  # Cleanup the properties, of component schemas, that exists in the base but not in the spec.
+  #
+  # @param [Hash] base
+  # @param [Hash] spec
+  def cleanup_components_schemas!(base, spec)
+    cleanup_hash!(base, spec, 'components.schemas.*')
+    cleanup_hash!(base, spec, 'components.schemas.*.properties.*')
+  end
+
+  # Cleanup specific elements that exists in the base but not in the spec
+  #
+  # @param [Hash] base
+  # @param [Hash] spec
+  def cleanup!(base, spec)
+    # cleanup URLs
+    cleanup_hash!(base, spec, 'paths.*')
+
+    # cleanup HTTP methods
+    cleanup_hash!(base, spec, 'paths.*.*')
+
+    # cleanup parameters
+    cleanup_array!(base, spec, 'paths.*.*.parameters', %w[name in])
+
+    # cleanup requestBody
+    cleanup_hash!(base, spec, 'paths.*.*.requestBody.content.application/json.schema.properties.*')
+    cleanup_hash!(base, spec, 'paths.*.*.requestBody.content.application/json.example.*')
+
+    # cleanup responses
+    cleanup_hash!(base, spec, 'paths.*.*.responses.*.content.application/json.schema.properties.*')
+    cleanup_hash!(base, spec, 'paths.*.*.responses.*.content.application/json.example.*')
+    base
+  end
+
+  private
+
+  def cleanup_array!(base, spec, selector, fields_for_identity = [])
+    marshal = lambda do |obj|
+      Marshal.dump(slice(obj, fields_for_identity))
+    end
+
+    RSpec::OpenAPI::HashHelper::matched_paths(base, selector).each do |paths|
+      target_array = base.dig(*paths)
+      spec_array = spec.dig(*paths)
+      unless target_array.is_a?(Array) && spec_array.is_a?(Array)
+        next
+      end
+      spec_identities = Set.new(spec_array.map(&marshal))
+      target_array.select! { |e| spec_identities.include?(marshal.call(e)) }
+      target_array.sort_by! { |param| fields_for_identity.map {|f| param[f] }.join('-') }
+      # Keep the last duplicate to produce the result stably
+      deduplicated = target_array.reverse.uniq { |param| slice(param, fields_for_identity) }.reverse
+      target_array.replace(deduplicated)
+    end
+    base
+  end
+
+  def cleanup_hash!(base, spec, selector)
+    RSpec::OpenAPI::HashHelper::matched_paths(base, selector).each do |paths|
+      exist_in_base = !base.dig(*paths).nil?
+      not_in_spec = spec.dig(*paths).nil?
+      if exist_in_base && not_in_spec
+        if paths.size == 1
+          base.delete(paths.last)
+        else
+          parent_node = base.dig(*paths[0..-2])
+          parent_node.delete(paths.last)
+        end
+      end
+    end
+    base
+  end
+
+  def slice(obj, fields_for_identity)
+    if fields_for_identity.any?
+      obj.slice(*fields_for_identity)
+    else
+      obj
+    end
+  end
+end

data/lib/rspec/openapi/version.rb

@@ -1,5 +1,5 @@
 module RSpec
   module OpenAPI
-    VERSION = '0.6.1'
+    VERSION = '0.7.0'
   end
 end

data/lib/rspec/openapi.rb

@@ -11,8 +11,18 @@ module RSpec::OpenAPI
   @request_headers = []
   @servers = []
   @example_types = %i[request]
+  @response_headers = []
 
   class << self
-    attr_accessor :path, :comment, :enable_example, :description_builder, :info, :application_version, :request_headers, :servers, :example_types
+    attr_accessor :path,
+                  :comment,
+                  :enable_example,
+                  :description_builder,
+                  :info,
+                  :application_version,
+                  :request_headers,
+                  :servers,
+                  :example_types,
+                  :response_headers
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-openapi
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Takashi Kokubun
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-07-08 00:00:00.000000000 Z
+date: 2022-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -57,11 +57,14 @@ files:
 - bin/console
 - bin/setup
 - lib/rspec/openapi.rb
+- lib/rspec/openapi/components_updater.rb
 - lib/rspec/openapi/default_schema.rb
+- lib/rspec/openapi/hash_helper.rb
 - lib/rspec/openapi/hooks.rb
 - lib/rspec/openapi/record.rb
 - lib/rspec/openapi/record_builder.rb
 - lib/rspec/openapi/schema_builder.rb
+- lib/rspec/openapi/schema_cleaner.rb
 - lib/rspec/openapi/schema_file.rb
 - lib/rspec/openapi/schema_merger.rb
 - lib/rspec/openapi/version.rb
@@ -74,7 +77,7 @@ metadata:
   homepage_uri: https://github.com/k0kubun/rspec-openapi
   source_code_uri: https://github.com/k0kubun/rspec-openapi
   changelog_uri: https://github.com/k0kubun/rspec-openapi/blob/master/CHANGELOG.md
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -89,8 +92,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 3.1.6
+signing_key: 
 specification_version: 4
 summary: Generate OpenAPI schema from RSpec request specs
 test_files: []