rspec-openapi 0.4.0 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 71067082bcf502d2e38341d6c357ee596851cefa9ff4e95b4ac34249261782df
-  data.tar.gz: '03279a96e39df1126d9fac2858903382654d2daa3121d415cf163b0bb1117fd1'
+  metadata.gz: 3bf318171323fbd3fa8d664a4f34ec1fe5af39a4d39ab5ee7b020b3871a31cb4
+  data.tar.gz: 610173247f3b9c99c7f5d2461bad49ae1d9000d7c8f63dfc4ac884472830c005
 SHA512:
-  metadata.gz: 8a3344f5ee11410e189661e1ec4a6e39ab9775e2554a9a7c92818bfee71de670ec606539ccb71f60da70b727b1e8d65366507640496947e181e2bbe25251dbe2
-  data.tar.gz: e332d6b082d4d6215535e90b750afaf2228310f989916f7b4d1b770c972ef055f329b0c84f37dba070719b4bbee7fcb47ec7d3f0c422af66b4bd712493b51e46
+  metadata.gz: 4b8c0402fe94dbcc43353c210acb1c9c4b182331020670bb8955dc4abf17a18732852fc4b191a3d1ded1d3613ef5e0059aa79e09084eb23bd9ce7ca5beec9e25
+  data.tar.gz: 6c4cd49edbaea41dfc1c2b17c89ec85dac8e1063612ff29f3c63dccde9dacd7a19eb276253363f1091a19976e0e6a20d40dc32f5deae36fa291e17f054b22eaf

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## v0.4.3
+
+* Allow customizing `schema`, `description`, and `tags` through `:openapi` metadata
+  [#36](https://github.com/k0kubun/rspec-openapi/pull/36)
+
+## v0.4.2
+
+* Allow using Proc as `RSpec::OpenAPI.path`
+  [#35](https://github.com/k0kubun/rspec-openapi/pull/35)
+
+## v0.4.1
+
+* Add `RSpec::OpenAPI.example_types` to hook types other than `type: :request`.
+  [#32](https://github.com/k0kubun/rspec-openapi/pull/32)
+
 ## v0.4.0
 
 * Drop `RSpec::OpenAPI.output` introduced in v0.3.20

data/README.md

@@ -24,7 +24,7 @@ gem 'rspec-openapi', group: :test
 Run rspec with OPENAPI=1 to generate `doc/openapi.yaml` for your request specs.
 
 ```bash
-$ OPENAPI=1 rspec
+$ OPENAPI=1 bundle exec rspec
 ```
 
 ### Example
@@ -111,6 +111,15 @@ RSpec::OpenAPI.path = 'doc/schema.yaml'
 # Change the output type to JSON
 RSpec::OpenAPI.path = 'doc/schema.json'
 
+# Or generate multiple partial schema files, given an RSpec example
+RSpec::OpenAPI.path = -> (example) {
+  case example.file_path
+  when %r[spec/requests/api/v1/] then 'doc/openapi/v1.yaml'
+  when %r[spec/requests/api/v2/] then 'doc/openapi/v2.yaml'
+  else 'doc/openapi.yaml'
+  end
+}
+
 # Disable generating `example`
 RSpec::OpenAPI.enable_example = false
 
@@ -135,6 +144,9 @@ EOS
 
 # Generate a custom description, given an RSpec example
 RSpec::OpenAPI.description_builder = -> (example) { example.description }
+
+# Change the example type(s) that will generate schema
+RSpec::OpenAPI.example_types = %i[request]
 ```
 
 ### How can I add information which can't be generated from RSpec?
@@ -160,22 +172,21 @@ RSpec.describe '/resources', type: :request do
 end
 ```
 
-## Project status
-
-Beta
+## Customizations
 
-Basic features are there, and some people are already using this.
+Some examples' attributes can be overwritten via RSpec metadata options. Example:
 
-### Other missing features with notes
+```rb
+  describe 'GET /api/v1/posts', openapi: {
+    summary: 'list all posts',
+    description: 'list all posts ordered by pub_date',
+    tags: %w[v1 posts],
+  } do
+    # ...
+  end
+```
 
-* Delete obsoleted endpoints
-  * Give up, or at least make the feature optional?
-  * Running all to detect obsoleted endpoints is sometimes not realistic anyway.
-* Intelligent merges
-  * To maintain both automated changes and manual edits, the schema merge needs to be intelligent.
-  * We'll just deep-reverse-merge schema for now, but if there's a $ref for example, modifications
-    there should be rerouted to the referenced object.
-  * A type could be an array of all possible types when merged.
+**NOTE**: `description` key will override also the one provided by `RSpec::OpenAPI.description_builder` method.
 
 ## Links
 

data/lib/rspec/openapi/hooks.rb

@@ -5,34 +5,36 @@ require 'rspec/openapi/schema_builder'
 require 'rspec/openapi/schema_file'
 require 'rspec/openapi/schema_merger'
 
-records = []
-records_errors = []
+path_records = Hash.new { |h, k| h[k] = [] }
+error_records = {}
 
 RSpec.configuration.after(:each) do |example|
-  if example.metadata[:type] == :request && example.metadata[:openapi] != false
+  if RSpec::OpenAPI.example_types.include?(example.metadata[:type]) && example.metadata[:openapi] != false
+    path = RSpec::OpenAPI.path.yield_self { |path| path.is_a?(Proc) ? path.call(example) : path }
     record = RSpec::OpenAPI::RecordBuilder.build(self, example: example)
-    records << record if record
+    path_records[path] << record if record
   end
 end
 
 RSpec.configuration.after(:suite) do
   title = File.basename(Dir.pwd)
-  RSpec::OpenAPI::SchemaFile.new(RSpec::OpenAPI.path).edit do |spec|
-    RSpec::OpenAPI::SchemaMerger.reverse_merge!(spec, RSpec::OpenAPI::DefaultSchema.build(title))
-    records.each do |record|
-      begin
-        RSpec::OpenAPI::SchemaMerger.reverse_merge!(spec, RSpec::OpenAPI::SchemaBuilder.build(record))
-      rescue StandardError, NotImplementedError => e # e.g. SchemaBuilder raises a NotImplementedError
-        # NOTE: Don't fail the build
-        records_errors << [e, record]
+  path_records.each do |path, records|
+    RSpec::OpenAPI::SchemaFile.new(path).edit do |spec|
+      RSpec::OpenAPI::SchemaMerger.reverse_merge!(spec, RSpec::OpenAPI::DefaultSchema.build(title))
+      records.each do |record|
+        begin
+          RSpec::OpenAPI::SchemaMerger.reverse_merge!(spec, RSpec::OpenAPI::SchemaBuilder.build(record))
+        rescue StandardError, NotImplementedError => e # e.g. SchemaBuilder raises a NotImplementedError
+          error_records[e] = record # Avoid failing the build
+        end
       end
     end
   end
-  if records_errors.any?
+  if error_records.any?
     error_message = <<~EOS
-      RSpec::OpenAPI got errors building #{records_errors.size} requests
-      
-      #{records_errors.map {|e, record| "#{e.inspect}: #{record.inspect}" }.join("\n")}
+      RSpec::OpenAPI got errors building #{error_records.size} requests
+
+      #{error_records.map {|e, record| "#{e.inspect}: #{record.inspect}" }.join("\n")}
     EOS
     colorizer = ::RSpec::Core::Formatters::ConsoleCodes
     RSpec.configuration.reporter.message colorizer.wrap(error_message, :failure)

data/lib/rspec/openapi/record_builder.rb

@@ -40,6 +40,8 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
       headers_arr << [header, header_value] if header_value
     end
 
+    metadata_options = example.metadata[:openapi] || {}
+
     RSpec::OpenAPI::Record.new(
       method: request.request_method,
       path: path,
@@ -48,9 +50,9 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
       request_params: raw_request_params(request),
       request_content_type: request.media_type,
       request_headers: request_headers,
-      summary: summary,
-      tags: tags,
-      description: RSpec::OpenAPI.description_builder.call(example),
+      summary: metadata_options[:summary] || summary,
+      tags: metadata_options[:tags] || tags,
+      description: metadata_options[:description] || RSpec::OpenAPI.description_builder.call(example),
       status: response.status,
       response_body: response_body,
       response_content_type: response.media_type,

data/lib/rspec/openapi/version.rb

@@ -1,5 +1,5 @@
 module RSpec
   module OpenAPI
-    VERSION = '0.4.0'
+    VERSION = '0.4.3'
   end
 end

data/lib/rspec/openapi.rb

@@ -9,8 +9,9 @@ module RSpec::OpenAPI
   @application_version = '1.0.0'
   @request_headers = []
   @server_urls = []
+  @example_types = %i[request]
 
   class << self
-    attr_accessor :path, :comment, :enable_example, :description_builder, :application_version, :request_headers, :server_urls
+    attr_accessor :path, :comment, :enable_example, :description_builder, :application_version, :request_headers, :server_urls, :example_types
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-openapi
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.3
 platform: ruby
 authors:
 - Takashi Kokubun
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-10-11 00:00:00.000000000 Z
+date: 2022-03-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -90,7 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Generate OpenAPI schema from RSpec request specs