rspec-openapi 0.35.0 → 0.36.0

data/lib/rspec/openapi/schema_file.rb

@@ -3,11 +3,11 @@
 require 'fileutils'
 require 'yaml'
 require 'json'
+require 'stringio'
 
 # For Ruby 2.7
 require 'date'
 
-# TODO: Support JSON
 class RSpec::OpenAPI::SchemaFile
   # @param [String] path
   def initialize(path)
@@ -16,28 +16,24 @@ class RSpec::OpenAPI::SchemaFile
 
   # Reads the existing spec, lets the block mutate it, writes the result back
   # and returns the (symbolized) spec so it can be mirrored to other files.
+  # A document that does not load is left as it is.
   # @return [Hash]
-  def edit(&block)
+  def edit
     spec = read
-    block.call(spec)
+    begin
+      yield spec
+    ensure
+      write(spec)
+    end
     spec
-  ensure
-    write(spec)
   end
 
   # Writes an already-built spec to this file, choosing the format from the
-  # file extension.
+  # file extension. Both formats write the symbol keys as strings themselves.
   # @param [Hash] spec
   def write(spec)
-    stringified = RSpec::OpenAPI::KeyTransformer.stringify(spec)
     FileUtils.mkdir_p(File.dirname(@path))
-    output =
-      if json?
-        JSON.pretty_generate(stringified)
-      else
-        prepend_comment(YAML.dump(stringified))
-      end
-    File.write(@path, output)
+    File.write(@path, json? ? JSON.pretty_generate(spec) : yaml_document(spec))
   end
 
   private
@@ -46,18 +42,29 @@ class RSpec::OpenAPI::SchemaFile
   def read
     return {} unless File.exist?(@path)
 
-    content = YAML.safe_load(File.read(@path), permitted_classes: [Date, Time]) # this can also parse JSON
-    return {} if content.nil?
+    content = File.read(@path)
+    spec = json? ? read_json(content) : RSpec::OpenAPI::YAMLLoader.load(content)
+    spec.nil? ? {} : spec
+  end
+
+  def read_json(content)
+    return nil if content.match?(/\A\s*\z/)
 
-    RSpec::OpenAPI::KeyTransformer.symbolize(content)
+    spec = JSON.parse(content, symbolize_names: true, max_nesting: false)
+    RSpec::OpenAPI::KeyTransformer.normalize_example_names!(spec)
   end
 
-  def prepend_comment(content)
-    return content if RSpec::OpenAPI.comment.nil?
+  def yaml_document(spec)
+    io = StringIO.new(+'')
+    io.write(comment_lines) unless RSpec::OpenAPI.comment.nil?
+    RSpec::OpenAPI::YAMLDumper.dump(spec, io)
+    io.string
+  end
 
+  def comment_lines
     comment = RSpec::OpenAPI.comment.dup
     comment << "\n" unless comment.end_with?("\n")
-    "#{comment.gsub(/^/, '# ').gsub(/^# \n/, "#\n")}#{content}"
+    comment.gsub(/^/, '# ').gsub(/^# \n/, "#\n")
   end
 
   def json?

data/lib/rspec/openapi/schema_merger.rb

@@ -25,6 +25,16 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
     merge_schema!(base, RSpec::OpenAPI::KeyTransformer.symbolize(spec))
   end
 
+  # Same, for a spec built for this merge alone, like the schema of a record.
+  # Its keys are symbols already, and its hashes and arrays become part of base
+  # rather than being copied, so the caller must not use them afterwards.
+  #
+  # @param [Hash] base
+  # @param [Hash] spec
+  def merge_built!(base, spec)
+    merge_schema!(base, spec)
+  end
+
   SCHEMA_KEYS = [:schema, :schemas, :itemSchema].freeze
   DATA_KEYS = [:example, :examples, :default, :enum].freeze
   NUMERIC_TYPES = ['integer', 'number'].freeze
@@ -32,6 +42,8 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
     :title, :description, :deprecated, :readOnly, :writeOnly, :example, :examples, :default, :externalDocs, :xml,
     :discriminator,
   ].freeze
+  # Like nullable, readOnly describes the whole value, so it stays beside a oneOf.
+  ONE_OF_WRAPPER_KEYS = [:nullable, :readOnly].freeze
 
   private
 
@@ -63,6 +75,8 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
   def merge_schema_entry!(base, key, value, in_schema)
     if in_schema && key == :properties && base[key].is_a?(Hash) && value.is_a?(Hash)
       value.each { |name, property| merge_entry!(base[key], name, property, true) }
+    elsif in_schema && key == :readOnly
+      merge_read_only!(base, value)
     elsif DATA_KEYS.include?(key)
       merge_data!(base, key, value)
     else
@@ -70,6 +84,12 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
     end
   end
 
+  # A property only responses hold is readOnly, one a request sends is not. So
+  # false wins, and a side without an opinion leaves the other's.
+  def merge_read_only!(base, value)
+    base[:readOnly] = value && base.fetch(:readOnly, true)
+  end
+
   # Recorded data stays data however it is shaped, so a field named like a
   # schema key never gets merged as one.
   def merge_data!(base, key, value)
@@ -137,6 +157,7 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
 
     one_of_variants(spec).each { |variant| merge_variant!(base, variant) }
     base[:nullable] = true if nullable
+    merge_read_only!(base, spec[:readOnly]) if spec.key?(:readOnly)
     base
   end
 
@@ -156,7 +177,7 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
   end
 
   def one_of_variants(schema)
-    variants = schema[:oneOf] || [schema.reject { |key, _| key == :nullable }]
+    variants = schema[:oneOf] || [schema.reject { |key, _| ONE_OF_WRAPPER_KEYS.include?(key) }]
     variants.reject { |variant| variant.is_a?(Hash) && variant.empty? }
   end
 

data/lib/rspec/openapi/schema_sorter.rb

@@ -23,7 +23,12 @@ class << RSpec::OpenAPI::SchemaSorter = Object.new
       deep_sort_by_selector!(spec, "#{operation}.responses")
 
       # content-type
+      deep_sort_by_selector!(spec, "#{operation}.requestBody.content")
       deep_sort_by_selector!(spec, "#{operation}.responses.*.content")
+
+      # named examples (keyed by test description)
+      deep_sort_by_selector!(spec, "#{operation}.requestBody.content.*.examples")
+      deep_sort_by_selector!(spec, "#{operation}.responses.*.content.*.examples")
     end
   end
 
@@ -32,14 +37,29 @@ class << RSpec::OpenAPI::SchemaSorter = Object.new
   # @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))
+    RSpec::OpenAPI::HashHelper.each_matched(base, nil, selector) do |_parent, _key, hash, _counterpart|
+      deep_sort_hash!(hash)
     end
   end
 
   # Re-inserting a key moves it to the end, so re-inserting every key in sorted
-  # order sorts the hash in place.
+  # order sorts the hash in place. A document read back from a file is sorted
+  # already, so a hash whose keys are in order is left alone, without the two
+  # arrays of keys a sort would build. The keys are all symbols, which sort as
+  # their names do.
   def deep_sort_hash!(hash)
-    hash.keys.sort_by(&:to_s).each { |key| hash[key.to_sym] = hash.delete(key) }
+    return if sorted?(hash)
+
+    hash.keys.sort.each { |key| hash[key] = hash.delete(key) }
+  end
+
+  def sorted?(hash)
+    previous = nil
+    hash.each_key do |key|
+      return false if previous && previous > key
+
+      previous = key
+    end
+    true
   end
 end

data/lib/rspec/openapi/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module OpenAPI
-    VERSION = '0.35.0'
+    VERSION = '0.36.0'
   end
 end

data/lib/rspec/openapi/yaml_dumper.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+# Writes a document straight to the libyaml emitter. YAML.dump first builds a
+# tree of Psych nodes and then walks it to make the same emitter calls, so the
+# output is the same without the tree. Keys are written as strings, which is
+# what they are read back as, so the document needs no stringified copy.
+#
+# Nothing in a document is shared, so there are no anchors to find and the
+# bookkeeping for them is skipped.
+class RSpec::OpenAPI::YAMLDumper < Psych::Visitors::YAMLTree
+  # @param [Object] object
+  # @param [IO, StringIO] io
+  def self.dump(object, io)
+    dumper = create({}, Psych::Emitter.new(io))
+    dumper << object
+    dumper.finish
+    io
+  end
+
+  # Stands in for the emitter while the superclass writes a string, to keep
+  # the arguments of the one scalar call it makes.
+  class Recorder
+    attr_reader :scalar_arguments
+
+    def initialize(emitter)
+      @emitter = emitter
+    end
+
+    def scalar(value, anchor, tag, plain, quoted, style) # rubocop:disable Metrics/ParameterLists
+      # The emitter copies a string of any encoding but UTF-8 on every call.
+      value = value.dup.force_encoding(Encoding::UTF_8) if value.encoding != Encoding::UTF_8 && value.ascii_only?
+      @scalar_arguments = [value, tag, plain, quoted, style].freeze
+      @emitter.scalar(value, anchor, tag, plain, quoted, style)
+    end
+  end
+  private_constant :Recorder
+
+  def initialize(emitter, scanner, options)
+    super
+    # How a string is written takes several regexp matches to decide, and a
+    # document repeats its keys and the names of its types thousands of times.
+    # So the decision is kept by key, which saves the string of the key too,
+    # and by string.
+    @key_scalars = {}.compare_by_identity
+    @string_scalars = {}
+  end
+
+  def visit_Hash(hash) # rubocop:disable Naming/MethodName
+    @emitter.start_mapping(nil, nil, true, Psych::Nodes::Mapping::BLOCK)
+    hash.each do |key, value|
+      emit_key(key)
+      accept(value)
+    end
+    @emitter.end_mapping
+  end
+
+  def visit_Array(array) # rubocop:disable Naming/MethodName
+    @emitter.start_sequence(nil, nil, true, Psych::Nodes::Sequence::BLOCK)
+    array.each { |item| accept(item) }
+    @emitter.end_sequence
+  end
+
+  def visit_String(string) # rubocop:disable Naming/MethodName
+    scalar = @string_scalars[string]
+    return emit_scalar(scalar) if scalar
+
+    @string_scalars[string] = recording { super }
+  end
+
+  private
+
+  def emit_key(key)
+    scalar = @key_scalars[key]
+    return emit_scalar(scalar) if scalar
+
+    name = key.to_s
+    visit_String(name)
+    @key_scalars[key] = @string_scalars[name]
+  end
+
+  def emit_scalar(scalar)
+    @emitter.scalar(scalar[0], nil, scalar[1], scalar[2], scalar[3], scalar[4])
+  end
+
+  def recording
+    emitter = @emitter
+    @emitter = recorder = Recorder.new(emitter)
+    yield
+    recorder.scalar_arguments
+  ensure
+    @emitter = emitter
+  end
+
+  # :nocov:
+  # Reached by values other than hashes, arrays and plain scalars, such as the
+  # dates of a hand-written document, which the suite does not hold.
+  def register(_target, yaml_obj)
+    yaml_obj
+  end
+  # :nocov:
+end

data/lib/rspec/openapi/yaml_loader.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'date'
+
+# Builds the document with symbol keys straight from the parser events.
+# YAML.safe_load builds a tree of Psych nodes first and hands back string keys,
+# which KeyTransformer.symbolize then converted in a copy of the whole document.
+# The names of examples are normalized on the way, as that copy did.
+#
+# A key names an entry, so it is a string however it reads: `200:` is the name
+# of a response, not a number. Resolving it as YAML.safe_load does would give
+# a key with no name to take.
+#
+# Anchors, tags and merge keys are left to YAML.safe_load, which accepts or
+# rejects them as it always did. A valid alias follows its anchor, so only a
+# dangling one gets this far, and it is handed off as well.
+class RSpec::OpenAPI::YAMLLoader < Psych::Handler
+  class Unsupported < StandardError; end
+  private_constant :Unsupported
+
+  PERMITTED_CLASSES = [Date, Time].freeze
+  # Marks a mapping waiting for its next key.
+  NONE = Object.new.freeze
+  private_constant :NONE
+
+  # @param [String] yaml
+  # @return [Object, nil] the first document, or nil when there is none
+  def self.load(yaml)
+    loader = new
+    Psych::Parser.new(loader).parse(yaml)
+    loader.root
+  rescue Unsupported
+    RSpec::OpenAPI::KeyTransformer.symbolize(YAML.safe_load(yaml, permitted_classes: PERMITTED_CLASSES))
+  end
+
+  def initialize
+    super
+    class_loader = Psych::ClassLoader::Restricted.new(PERMITTED_CLASSES.map(&:name), [])
+    @scanner = Psych::ScalarScanner.new(class_loader)
+    @documents = []
+    @containers = [@documents]
+    # Per open mapping: the key waiting for its value, and whether the mapping
+    # holds named examples.
+    @pending_keys = []
+    @examples_maps = []
+  end
+
+  def root
+    @documents.first
+  end
+
+  def scalar(value, anchor, tag, _plain, quoted, _style) # rubocop:disable Metrics/ParameterLists
+    supported!(anchor, tag, value)
+    value = @scanner.tokenize(value) unless quoted || key_next?
+    add(value)
+  end
+
+  def start_sequence(anchor, tag, _implicit, _style)
+    supported!(anchor, tag)
+    @containers.push(add([]))
+  end
+
+  def end_sequence
+    @containers.pop
+  end
+
+  def start_mapping(anchor, tag, _implicit, _style)
+    supported!(anchor, tag)
+    @examples_maps.push(@containers.last.is_a?(Hash) && @pending_keys.last == :examples)
+    @containers.push(add({}))
+    @pending_keys.push(NONE)
+  end
+
+  def end_mapping
+    @containers.pop
+    @pending_keys.pop
+    @examples_maps.pop
+  end
+
+  def alias(_anchor)
+    raise Unsupported
+  end
+
+  private
+
+  # A `<<` key merges its value into the mapping, so it is handed off too.
+  def supported!(anchor, tag, value = nil)
+    raise Unsupported if anchor || tag || value == '<<'
+  end
+
+  # A sequence inside a mapping pushes no pending key, so the mapping's NONE
+  # shows through it and the container is checked as well.
+  def key_next?
+    @pending_keys.last.equal?(NONE) && @containers.last.is_a?(Hash)
+  end
+
+  # Values arrive in document order: onto the open sequence, or as the key and
+  # then the value of the open mapping. The documents are the outermost
+  # sequence.
+  def add(value)
+    container = @containers.last
+    if container.is_a?(Array)
+      container << value
+    elsif @pending_keys.last.equal?(NONE)
+      @pending_keys[-1] = key_for(value)
+    else
+      container[@pending_keys[-1]] = value
+      @pending_keys[-1] = NONE
+    end
+    value
+  end
+
+  def key_for(key)
+    key = RSpec::OpenAPI::ExampleKey.normalize(key) if @examples_maps.last && key.is_a?(String)
+    key.to_sym
+  end
+end

data/lib/rspec/openapi.rb

@@ -9,6 +9,7 @@ require 'rspec/openapi/stream_parser'
 require 'rspec/openapi/record_builder'
 require 'rspec/openapi/exchange_recorder'
 require 'rspec/openapi/parallel_records'
+require 'rspec/openapi/partial_run'
 require 'rspec/openapi/result_recorder'
 require 'rspec/openapi/schema_builder'
 require 'rspec/openapi/schema_file'
@@ -17,6 +18,8 @@ require 'rspec/openapi/schema_merger'
 require 'rspec/openapi/schema_cleaner'
 require 'rspec/openapi/schema_sorter'
 require 'rspec/openapi/key_transformer'
+require 'rspec/openapi/yaml_dumper'
+require 'rspec/openapi/yaml_loader'
 require 'rspec/openapi/shared_hooks'
 require 'rspec/openapi/extractors'
 require 'rspec/openapi/extractors/shared_extractor'
@@ -32,6 +35,11 @@ module RSpec::OpenAPI
     'text/event-stream',
   ].freeze
 
+  # Properties a server assigns by convention, for read_only_builder. Foreign
+  # keys such as `user_id` are left out, since clients send them.
+  DEFAULT_READ_ONLY_KEYS = ['id', 'uuid', 'created_at', 'updated_at'].freeze
+  DEFAULT_READ_ONLY_BUILDER = ->(_example, key) { DEFAULT_READ_ONLY_KEYS.include?(key) }
+
   class Config
     class << self
       attr_accessor :debug_enabled
@@ -52,6 +60,7 @@ module RSpec::OpenAPI
   @summary_builder = ->(example) { example.metadata[:summary] }
   @tags_builder = ->(example) { example.metadata[:tags] }
   @formats_builder = ->(example) { example.metadata[:formats] }
+  @read_only_builder = nil
   @info = {}
   @application_version = '1.0.0'
   @openapi_version = '3.2.0'
@@ -65,6 +74,8 @@ module RSpec::OpenAPI
   @ignored_path_params = [:controller, :action, :format]
   @ignored_paths = []
   @post_process_hook = nil
+  # true or false forces the mode. nil lets each run decide, see PartialRun.
+  @partial_update = { '1' => true, '0' => false }[ENV.fetch('OPENAPI_PARTIAL_UPDATE', nil)]
 
   # This is the configuraion override file name we look for within each path.
   @config_filename = 'rspec_openapi.rb'
@@ -80,6 +91,7 @@ module RSpec::OpenAPI
                   :summary_builder,
                   :tags_builder,
                   :formats_builder,
+                  :read_only_builder,
                   :info,
                   :application_version,
                   :request_headers,
@@ -91,7 +103,8 @@ module RSpec::OpenAPI
                   :path_records,
                   :ignored_paths,
                   :ignored_path_params,
-                  :post_process_hook
+                  :post_process_hook,
+                  :partial_update
 
     attr_reader   :config_filename, :openapi_version
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-openapi
 version: !ruby/object:Gem::Version
-  version: 0.35.0
+  version: 0.36.0
 platform: ruby
 authors:
 - Takashi Kokubun
@@ -78,6 +78,7 @@ files:
 - lib/rspec/openapi/nullable_converter.rb
 - lib/rspec/openapi/operation_converter.rb
 - lib/rspec/openapi/parallel_records.rb
+- lib/rspec/openapi/partial_run.rb
 - lib/rspec/openapi/record.rb
 - lib/rspec/openapi/record_builder.rb
 - lib/rspec/openapi/result_recorder.rb
@@ -92,6 +93,8 @@ files:
 - lib/rspec/openapi/shared_hooks.rb
 - lib/rspec/openapi/stream_parser.rb
 - lib/rspec/openapi/version.rb
+- lib/rspec/openapi/yaml_dumper.rb
+- lib/rspec/openapi/yaml_loader.rb
 - rspec-openapi.gemspec
 homepage: https://github.com/exoego/rspec-openapi
 licenses:
@@ -99,7 +102,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.35.0
+  changelog_uri: https://github.com/exoego/rspec-openapi/releases/tag/v0.36.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: