rswag-specs 2.1.0 → 2.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d360f480ad502e00f5951e40882af98b2b1cc9f4d414c65e41495ca77494a3b0
-  data.tar.gz: 7492e978e971b80560cc1eba26b0b7426c6145745e6dea93be46a58ff200965f
+  metadata.gz: 540d37d1a9a9e90a4b062f65239029fdd9fcdcfec4622eb68ec4f90ec4eebab9
+  data.tar.gz: 9180d18a4a0d8ba624c42a38376270bdb0885da77f007cf001be3128d5929d66
 SHA512:
-  metadata.gz: 352cd0dd07a2c39626f58388ffa1b069f30c538d666bab8206f7c027df7412a3fcaac79a9855e7c260b0c4a98ea0d5c58e12503cd665701a9ccfdeac6c9bf19c
-  data.tar.gz: bf66adcb9ff47d01fe283782f87bb4a6ec996e72eddd1850cb498f81b665aecf49393bb480fad81b1ee71f68cd03dc90307658b9b1b02c66be976dd547bba816
+  metadata.gz: 4da3cd01812d9d8b8d8e28a4f35400cabcae133efd3192864eaa4820a9210c82dd78b35e353abaf74856d6f822fbf3f3eac94fa2c3dbe461f7b3167a129f7e6d
+  data.tar.gz: f4e261ec8b205d949058e8a124964250cfcef4a26ff93c59fa8fb269acc0e0b9c565e2b0bac2ae8071a92146d69a685b902bf11e6939282a27abe1c13cdbd1a9

data/Rakefile

@@ -20,8 +20,4 @@ RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-
-
-
 Bundler::GemHelper.install_tasks
-

data/lib/generators/rspec/swagger_generator.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 require 'rswag/route_parser'
 require 'rails/generators'
 
 module Rspec
   class SwaggerGenerator < ::Rails::Generators::NamedBase
-    source_root File.expand_path('../templates', __FILE__)
+    source_root File.expand_path('templates', __dir__)
 
     def setup
       @routes = Rswag::RouteParser.new(controller_path).routes

data/lib/generators/rspec/templates/spec.rb

@@ -19,7 +19,11 @@ RSpec.describe '<%= controller_path %>', type: :request do
 <%      end -%>
 
         after do |example|
-          example.metadata[:response][:examples] = { 'application/json' => JSON.parse(response.body, symbolize_names: true) }
+          example.metadata[:response][:content] = {
+            'application/json' => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
         end
         run_test!
       end

data/lib/generators/rswag/specs/install/install_generator.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
+
 require 'rails/generators'
 
 module Rswag
   module Specs
-
     class InstallGenerator < Rails::Generators::Base
-      source_root File.expand_path('../templates', __FILE__)
+      source_root File.expand_path('templates', __dir__)
 
       def add_swagger_helper
         template('swagger_helper.rb', 'spec/swagger_helper.rb')

data/lib/generators/rswag/specs/install/templates/swagger_helper.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rails_helper'
 
 RSpec.configure do |config|
@@ -13,13 +15,29 @@ RSpec.configure do |config|
   # document below. You can override this behavior by adding a swagger_doc tag to the
   # the root example_group in your specs, e.g. describe '...', swagger_doc: 'v2/swagger.json'
   config.swagger_docs = {
-    'v1/swagger.json' => {
-      swagger: '2.0',
+    'v1/swagger.yaml' => {
+      openapi: '3.0.1',
       info: {
         title: 'API V1',
         version: 'v1'
       },
-      paths: {}
+      paths: {},
+      servers: [
+        {
+          url: 'https://{defaultHost}',
+          variables: {
+            defaultHost: {
+              default: 'www.example.com'
+            }
+          }
+        }
+      ]
     }
   }
+
+  # Specify the format of the output Swagger file when running 'rswag:specs:swaggerize'.
+  # The swagger_docs configuration option has the filename including format in
+  # the key, this may want to be changed to avoid putting yaml in json files.
+  # Defaults to json. Accepts ':json' and ':yaml'.
+  config.swagger_format = :yaml
 end

data/lib/rswag/route_parser.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rswag
   class RouteParser
     attr_reader :controller
@@ -9,7 +11,7 @@ module Rswag
     def routes
       ::Rails.application.routes.routes.select do |route|
         route.defaults[:controller] == controller
-      end.reduce({}) do |tree, route|
+      end.each_with_object({}) do |route, tree|
         path = path_from(route)
         verb = verb_from(route)
         tree[path] ||= { params: params_from(route), actions: {} }
@@ -28,7 +30,7 @@ module Rswag
 
     def verb_from(route)
       verb = route.verb
-      if verb.kind_of? String
+      if verb.is_a? String
         verb.downcase
       else
         verb.source.gsub(/[$^]/, '').downcase

data/lib/rswag/specs.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'rspec/core'
 require 'rswag/specs/example_group_helpers'
 require 'rswag/specs/example_helpers'
@@ -6,12 +8,12 @@ require 'rswag/specs/railtie' if defined?(Rails::Railtie)
 
 module Rswag
   module Specs
-
     # Extend RSpec with a swagger-based DSL
     ::RSpec.configure do |c|
       c.add_setting :swagger_root
       c.add_setting :swagger_docs
       c.add_setting :swagger_dry_run
+      c.add_setting :swagger_format
       c.extend ExampleGroupHelpers, type: :request
       c.include ExampleHelpers, type: :request
     end

data/lib/rswag/specs/configuration.rb

@@ -1,8 +1,8 @@
+# frozen_string_literal: true
+
 module Rswag
   module Specs
-
     class Configuration
-
       def initialize(rspec_config)
         @rspec_config = rspec_config
       end
@@ -12,6 +12,7 @@ module Rswag
           if @rspec_config.swagger_root.nil?
             raise ConfigurationError, 'No swagger_root provided. See swagger_helper.rb'
           end
+
           @rspec_config.swagger_root
         end
       end
@@ -21,6 +22,7 @@ module Rswag
           if @rspec_config.swagger_docs.nil? || @rspec_config.swagger_docs.empty?
             raise ConfigurationError, 'No swagger_docs defined. See swagger_helper.rb'
           end
+
           @rspec_config.swagger_docs
         end
       end
@@ -31,11 +33,26 @@ module Rswag
         end
       end
 
+      def swagger_format
+        @swagger_format ||= begin
+          @rspec_config.swagger_format = :json if @rspec_config.swagger_format.nil? || @rspec_config.swagger_format.empty?
+          raise ConfigurationError, "Unknown swagger_format '#{@rspec_config.swagger_format}'" unless [:json, :yaml].include?(@rspec_config.swagger_format)
+
+          @rspec_config.swagger_format
+        end
+      end
+
       def get_swagger_doc(name)
         return swagger_docs.values.first if name.nil?
         raise ConfigurationError, "Unknown swagger_doc '#{name}'" unless swagger_docs[name]
+
         swagger_docs[name]
       end
+
+      def get_swagger_doc_version(name)
+        doc = get_swagger_doc(name)
+        doc[:openapi] || doc[:swagger]
+      end
     end
 
     class ConfigurationError < StandardError; end

data/lib/rswag/specs/example_group_helpers.rb

@@ -1,20 +1,21 @@
+# frozen_string_literal: true
+
 module Rswag
   module Specs
     module ExampleGroupHelpers
-
-      def path(template, metadata={}, &block)
+      def path(template, metadata = {}, &block)
         metadata[:path_item] = { template: template }
         describe(template, metadata, &block)
       end
 
-      [ :get, :post, :patch, :put, :delete, :head, :options, :trace ].each do |verb|
+      [:get, :post, :patch, :put, :delete, :head, :options, :trace].each do |verb|
         define_method(verb) do |summary, &block|
           api_metadata = { operation: { verb: verb, summary: summary } }
           describe(verb, api_metadata, &block)
         end
       end
 
-      [ :operationId, :deprecated, :security ].each do |attr_name|
+      [:operationId, :deprecated, :security].each do |attr_name|
         define_method(attr_name) do |value|
           metadata[:operation][attr_name] = value
         end
@@ -23,13 +24,14 @@ module Rswag
       # NOTE: 'description' requires special treatment because ExampleGroup already
       # defines a method with that name. Provide an override that supports the existing
       # functionality while also setting the appropriate metadata if applicable
-      def description(value=nil)
+      def description(value = nil)
         return super() if value.nil?
+
         metadata[:operation][:description] = value
       end
 
       # These are array properties - note the splat operator
-      [ :tags, :consumes, :produces, :schemes ].each do |attr_name|
+      [:tags, :consumes, :produces, :schemes].each do |attr_name|
         define_method(attr_name) do |*value|
           metadata[:operation][attr_name] = value
         end
@@ -40,7 +42,7 @@ module Rswag
           attributes[:required] = true
         end
 
-        if metadata.has_key?(:operation)
+        if metadata.key?(:operation)
           metadata[:operation][:parameters] ||= []
           metadata[:operation][:parameters] << attributes
         else
@@ -49,7 +51,7 @@ module Rswag
         end
       end
 
-      def response(code, description, metadata={}, &block)
+      def response(code, description, metadata = {}, &block)
         metadata[:response] = { code: code, description: description }
         context(description, metadata, &block)
       end
@@ -60,6 +62,7 @@ module Rswag
 
       def header(name, attributes)
         metadata[:response][:headers] ||= {}
+
         metadata[:response][:headers][name] = attributes
       end
 
@@ -68,7 +71,11 @@ module Rswag
       # rspec-core ExampleGroup
       def examples(example = nil)
         return super() if example.nil?
-        metadata[:response][:examples] = example
+
+        metadata[:response][:content] =
+          example.each_with_object({}) do |(mime, example_object), memo|
+            memo[mime] = { example: example_object }
+          end
       end
 
       def run_test!(&block)

data/lib/rswag/specs/example_helpers.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
+
 require 'rswag/specs/request_factory'
 require 'rswag/specs/response_validator'
 
 module Rswag
   module Specs
     module ExampleHelpers
-
       def submit_request(metadata)
         request = RequestFactory.new.build_request(metadata, self)
 
@@ -19,10 +20,8 @@ module Rswag
           send(
             request[:verb],
             request[:path],
-            {
-              params: request[:payload],
-              headers: request[:headers]
-            }
+            params: request[:payload],
+            headers: request[:headers]
           )
         end
       end

data/lib/rswag/specs/extended_schema.rb

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
 require 'json-schema'
 
 module Rswag
   module Specs
     class ExtendedSchema < JSON::Schema::Draft4
-
       def initialize
         super
         @attributes['type'] = ExtendedTypeAttribute
@@ -13,9 +14,9 @@ module Rswag
     end
 
     class ExtendedTypeAttribute < JSON::Schema::TypeV4Attribute
+      def self.validate(current_schema, data, fragments, processor, validator, options = {})
+        return if data.nil? && (current_schema.schema['nullable'] == true || current_schema.schema['x-nullable'] == true)
 
-      def self.validate(current_schema, data, fragments, processor, validator, options={})
-        return if data.nil? && current_schema.schema['x-nullable'] == true
         super
       end
     end

data/lib/rswag/specs/railtie.rb

@@ -1,13 +1,14 @@
+# frozen_string_literal: true
+
 module Rswag
   module Specs
     class Railtie < ::Rails::Railtie
-
       rake_tasks do
-        load File.expand_path('../../../tasks/rswag-specs_tasks.rake', __FILE__)
+        load File.expand_path('../../tasks/rswag-specs_tasks.rake', __dir__)
       end
 
       generators do
-        require 'generators/rspec/swagger/swagger_generator.rb'
+        require 'generators/rspec/swagger_generator.rb'
       end
     end
   end

data/lib/rswag/specs/request_factory.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_support/core_ext/hash/slice'
 require 'active_support/core_ext/hash/conversions'
 require 'json'
@@ -5,7 +7,6 @@ require 'json'
 module Rswag
   module Specs
     class RequestFactory
-
       def initialize(config = ::Rswag::Specs.config)
         @config = config
       end
@@ -38,8 +39,8 @@ module Rswag
 
       def derive_security_params(metadata, swagger_doc)
         requirements = metadata[:operation][:security] || swagger_doc[:security] || []
-        scheme_names = requirements.flat_map { |r| r.keys }
-        schemes = (swagger_doc[:securityDefinitions] || {}).slice(*scheme_names).values
+        scheme_names = requirements.flat_map(&:keys)
+        schemes = security_version(scheme_names, swagger_doc)
 
         schemes.map do |scheme|
           param = (scheme[:type] == :apiKey) ? scheme.slice(:name, :in) : { name: 'Authorization', in: :header }
@@ -47,13 +48,55 @@ module Rswag
         end
       end
 
+      def security_version(scheme_names, swagger_doc)
+        if doc_version(swagger_doc).start_with?('2')
+          (swagger_doc[:securityDefinitions] || {}).slice(*scheme_names).values
+        else # Openapi3
+          if swagger_doc.key?(:securityDefinitions)
+            ActiveSupport::Deprecation.warn('Rswag::Specs: WARNING: securityDefinitions is replaced in OpenAPI3! Rename to components/securitySchemes (in swagger_helper.rb)')
+            swagger_doc[:components] ||= { securitySchemes: swagger_doc[:securityDefinitions] }
+            swagger_doc.delete(:securityDefinitions)
+          end
+          components = swagger_doc[:components] || {}
+          (components[:securitySchemes] || {}).slice(*scheme_names).values
+        end
+      end
+
       def resolve_parameter(ref, swagger_doc)
-        key = ref.sub('#/parameters/', '').to_sym
-        definitions = swagger_doc[:parameters]
+        key = key_version(ref, swagger_doc)
+        definitions = definition_version(swagger_doc)
         raise "Referenced parameter '#{ref}' must be defined" unless definitions && definitions[key]
+
         definitions[key]
       end
 
+      def key_version(ref, swagger_doc)
+        if doc_version(swagger_doc).start_with?('2')
+          ref.sub('#/parameters/', '').to_sym
+        else # Openapi3
+          if ref.start_with?('#/parameters/')
+            ActiveSupport::Deprecation.warn('Rswag::Specs: WARNING: #/parameters/ refs are replaced in OpenAPI3! Rename to #/components/parameters/')
+            ref.sub('#/parameters/', '').to_sym
+          else
+            ref.sub('#/components/parameters/', '').to_sym
+          end
+        end
+      end
+
+      def definition_version(swagger_doc)
+        if doc_version(swagger_doc).start_with?('2')
+          swagger_doc[:parameters]
+        else # Openapi3
+          if swagger_doc.key?(:parameters)
+            ActiveSupport::Deprecation.warn('Rswag::Specs: WARNING: parameters is replaced in OpenAPI3! Rename to components/parameters (in swagger_helper.rb)')
+            swagger_doc[:parameters]
+          else
+            components = swagger_doc[:components] || {}
+            components[:parameters]
+          end
+        end
+      end
+
       def add_verb(request, metadata)
         request[:verb] = metadata[:operation][:verb]
       end
@@ -61,21 +104,22 @@ module Rswag
       def add_path(request, metadata, swagger_doc, parameters, example)
         template = (swagger_doc[:basePath] || '') + metadata[:path_item][:template]
 
-        request[:path] = template.tap do |template|
+        request[:path] = template.tap do |path_template|
           parameters.select { |p| p[:in] == :path }.each do |p|
-            template.gsub!("{#{p[:name]}}", example.send(p[:name]).to_s)
+            path_template.gsub!("{#{p[:name]}}", example.send(p[:name]).to_s)
           end
 
           parameters.select { |p| p[:in] == :query }.each_with_index do |p, i|
-            template.concat(i == 0 ? '?' : '&')
-            template.concat(build_query_string_part(p, example.send(p[:name])))
+            path_template.concat(i.zero? ? '?' : '&')
+            path_template.concat(build_query_string_part(p, example.send(p[:name])))
           end
         end
       end
 
       def build_query_string_part(param, value)
         name = param[:name]
-        return "#{name}=#{value.to_s}" unless param[:type].to_sym == :array
+        type = param[:type] || param.dig(:schema, :type)
+        return "#{name}=#{value}" unless type&.to_sym == :array
 
         case param[:collectionFormat]
         when :ssv
@@ -94,43 +138,43 @@ module Rswag
       def add_headers(request, metadata, swagger_doc, parameters, example)
         tuples = parameters
           .select { |p| p[:in] == :header }
-          .map { |p| [ p[:name], example.send(p[:name]).to_s ] }
+          .map { |p| [p[:name], example.send(p[:name]).to_s] }
 
         # Accept header
         produces = metadata[:operation][:produces] || swagger_doc[:produces]
         if produces
-          accept = example.respond_to?(:'Accept') ? example.send(:'Accept') : produces.first
-          tuples << [ 'Accept', accept ]
+          accept = example.respond_to?(:Accept) ? example.send(:Accept) : produces.first
+          tuples << ['Accept', accept]
         end
 
         # Content-Type header
         consumes = metadata[:operation][:consumes] || swagger_doc[:consumes]
         if consumes
           content_type = example.respond_to?(:'Content-Type') ? example.send(:'Content-Type') : consumes.first
-          tuples << [ 'Content-Type', content_type ]
+          tuples << ['Content-Type', content_type]
         end
 
         # Rails test infrastructure requires rackified headers
         rackified_tuples = tuples.map do |pair|
           [
             case pair[0]
-              when 'Accept' then 'HTTP_ACCEPT'
-              when 'Content-Type' then 'CONTENT_TYPE'
-              when 'Authorization' then 'HTTP_AUTHORIZATION'
-              else pair[0]
+            when 'Accept' then 'HTTP_ACCEPT'
+            when 'Content-Type' then 'CONTENT_TYPE'
+            when 'Authorization' then 'HTTP_AUTHORIZATION'
+            else pair[0]
             end,
             pair[1]
           ]
         end
 
-        request[:headers] = Hash[ rackified_tuples ]
+        request[:headers] = Hash[rackified_tuples]
       end
 
       def add_payload(request, parameters, example)
         content_type = request[:headers]['CONTENT_TYPE']
         return if content_type.nil?
 
-        if [ 'application/x-www-form-urlencoded', 'multipart/form-data' ].include?(content_type)
+        if ['application/x-www-form-urlencoded', 'multipart/form-data'].include?(content_type)
           request[:payload] = build_form_payload(parameters, example)
         else
           request[:payload] = build_json_payload(parameters, example)
@@ -144,14 +188,18 @@ module Rswag
         # PROS: simple to implement, CONS: serialization/deserialization is bypassed in test
         tuples = parameters
           .select { |p| p[:in] == :formData }
-          .map { |p| [ p[:name], example.send(p[:name]) ] }
-        Hash[ tuples ]
+          .map { |p| [p[:name], example.send(p[:name])] }
+        Hash[tuples]
       end
 
       def build_json_payload(parameters, example)
         body_param = parameters.select { |p| p[:in] == :body }.first
         body_param ? example.send(body_param[:name]).to_json : nil
       end
+
+      def doc_version(doc)
+        doc[:openapi] || doc[:swagger] || '3'
+      end
     end
   end
 end

data/lib/rswag/specs/response_validator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_support/core_ext/hash/slice'
 require 'json-schema'
 require 'json'
@@ -6,7 +8,6 @@ require 'rswag/specs/extended_schema'
 module Rswag
   module Specs
     class ResponseValidator
-
       def initialize(config = ::Rswag::Specs.config)
         @config = config
       end
@@ -25,8 +26,8 @@ module Rswag
         expected = metadata[:response][:code].to_s
         if response.code != expected
           raise UnexpectedResponse,
-                "Expected response code '#{response.code}' to match '#{expected}'\n" \
-                "Response body: #{response.body}"
+            "Expected response code '#{response.code}' to match '#{expected}'\n" \
+              "Response body: #{response.body}"
         end
       end
 
@@ -41,12 +42,30 @@ module Rswag
         response_schema = metadata[:response][:schema]
         return if response_schema.nil?
 
+        version = @config.get_swagger_doc_version(metadata[:swagger_doc])
+        schemas = definitions_or_component_schemas(swagger_doc, version)
+
         validation_schema = response_schema
           .merge('$schema' => 'http://tempuri.org/rswag/specs/extended_schema')
-          .merge(swagger_doc.slice(:definitions))
+          .merge(schemas)
+
         errors = JSON::Validator.fully_validate(validation_schema, body)
         raise UnexpectedResponse, "Expected response body to match schema: #{errors[0]}" if errors.any?
       end
+
+      def definitions_or_component_schemas(swagger_doc, version)
+        if version.start_with?('2')
+          swagger_doc.slice(:definitions)
+        else # Openapi3
+          if swagger_doc.key?(:definitions)
+            ActiveSupport::Deprecation.warn('Rswag::Specs: WARNING: definitions is replaced in OpenAPI3! Rename to components/schemas (in swagger_helper.rb)')
+            swagger_doc.slice(:definitions)
+          else
+            components = swagger_doc[:components] || {}
+            { components: { schemas: components[:schemas] } }
+          end
+        end
+      end
     end
 
     class UnexpectedResponse < StandardError; end

data/lib/rswag/specs/swagger_formatter.rb

@@ -1,9 +1,12 @@
+# frozen_string_literal: true
+
 require 'active_support/core_ext/hash/deep_merge'
+require 'rspec/core/formatters/base_text_formatter'
 require 'swagger_helper'
 
 module Rswag
   module Specs
-    class SwaggerFormatter
+    class SwaggerFormatter < ::RSpec::Core::Formatters::BaseTextFormatter
 
       # NOTE: rspec 2.x support
       if RSPEC_VERSION > 2
@@ -19,25 +22,62 @@ module Rswag
 
       def example_group_finished(notification)
         # NOTE: rspec 2.x support
-        if RSPEC_VERSION > 2
-          metadata = notification.group.metadata
+        metadata = if RSPEC_VERSION > 2
+          notification.group.metadata
         else
-          metadata = notification.metadata
+          notification.metadata
         end
 
-        return unless metadata.has_key?(:response)
+        # !metadata[:document] won't work, since nil means we should generate
+        # docs.
+        return if metadata[:document] == false
+        return unless metadata.key?(:response)
+
         swagger_doc = @config.get_swagger_doc(metadata[:swagger_doc])
+
+        unless doc_version(swagger_doc).start_with?('2')
+          # This is called multiple times per file!
+          # metadata[:operation] is also re-used between examples within file
+          # therefore be careful NOT to modify its content here.
+          upgrade_request_type!(metadata)
+          upgrade_servers!(swagger_doc)
+          upgrade_oauth!(swagger_doc)
+          upgrade_response_produces!(swagger_doc, metadata)
+        end
+
         swagger_doc.deep_merge!(metadata_to_swagger(metadata))
       end
 
-      def stop(notification=nil)
+      def stop(_notification = nil)
         @config.swagger_docs.each do |url_path, doc|
+          unless doc_version(doc).start_with?('2')
+            doc[:paths]&.each_pair do |_k, v|
+              v.each_pair do |_verb, value|
+                is_hash = value.is_a?(Hash)
+                if is_hash && value.dig(:parameters)
+                  schema_param = value.dig(:parameters)&.find { |p| (p[:in] == :body || p[:in] == :formData) && p[:schema] }
+                  mime_list = value.dig(:consumes) || doc[:consumes]
+                  if value && schema_param && mime_list
+                    value[:requestBody] = { content: {} } unless value.dig(:requestBody, :content)
+                    value[:requestBody][:required] = true if schema_param[:required]
+                    mime_list.each do |mime|
+                      value[:requestBody][:content][mime] = { schema: schema_param[:schema] }
+                    end
+                  end
+
+                  value[:parameters].reject! { |p| p[:in] == :body || p[:in] == :formData }
+                end
+                remove_invalid_operation_keys!(value)
+              end
+            end
+          end
+
           file_path = File.join(@config.swagger_root, url_path)
           dirname = File.dirname(file_path)
-          FileUtils.mkdir_p dirname unless File.exists?(dirname)
+          FileUtils.mkdir_p dirname unless File.exist?(dirname)
 
           File.open(file_path, 'w') do |file|
-            file.write(JSON.pretty_generate(doc))
+            file.write(pretty_generate(doc))
           end
 
           @output.puts "Swagger doc generated at #{file_path}"
@@ -46,22 +86,120 @@ module Rswag
 
       private
 
+      def pretty_generate(doc)
+        if @config.swagger_format == :yaml
+          clean_doc = yaml_prepare(doc)
+          YAML.dump(clean_doc)
+        else # config errors are thrown in 'def swagger_format', no throw needed here
+          JSON.pretty_generate(doc)
+        end
+      end
+
+      def yaml_prepare(doc)
+        json_doc = JSON.pretty_generate(doc)
+        JSON.parse(json_doc)
+      end
+
       def metadata_to_swagger(metadata)
         response_code = metadata[:response][:code]
-        response = metadata[:response].reject { |k,v| k == :code }
+        response = metadata[:response].reject { |k, _v| k == :code }
 
         verb = metadata[:operation][:verb]
         operation = metadata[:operation]
-          .reject { |k,v| k == :verb }
+          .reject { |k, _v| k == :verb }
           .merge(responses: { response_code => response })
 
         path_template = metadata[:path_item][:template]
         path_item = metadata[:path_item]
-          .reject { |k,v| k == :template }
+          .reject { |k, _v| k == :template }
           .merge(verb => operation)
 
         { paths: { path_template => path_item } }
       end
+
+      def doc_version(doc)
+        doc[:openapi] || doc[:swagger] || '3'
+      end
+
+      def upgrade_response_produces!(swagger_doc, metadata)
+        # Accept header
+        mime_list = Array(metadata[:operation][:produces] || swagger_doc[:produces])
+        target_node = metadata[:response]
+        upgrade_content!(mime_list, target_node)
+        metadata[:response].delete(:schema)
+      end
+
+      def upgrade_content!(mime_list, target_node)
+        schema = target_node[:schema]
+        return if mime_list.empty? || schema.nil?
+        target_node[:content] ||= {}
+        target_node.merge!(content: {})
+
+        mime_list.each do |mime_type|
+          # TODO upgrade to have content-type specific schema
+          (target_node[:content][mime_type] ||= {}).merge!(schema: schema)
+        end
+      end
+
+      def upgrade_request_type!(metadata)
+        # No deprecation here as it seems valid to allow type as a shorthand
+        operation_nodes = metadata[:operation][:parameters] || []
+        path_nodes = metadata[:path_item][:parameters] || []
+        header_node = metadata[:response][:headers] || {}
+
+        (operation_nodes + path_nodes + [header_node]).each do |node|
+          if node && node[:type] && node[:schema].nil?
+            node[:schema] = { type: node[:type] }
+            node.delete(:type)
+          end
+        end
+      end
+
+      def upgrade_servers!(swagger_doc)
+        return unless swagger_doc[:servers].nil? && swagger_doc.key?(:schemes)
+
+        ActiveSupport::Deprecation.warn('Rswag::Specs: WARNING: schemes, host, and basePath are replaced in OpenAPI3! Rename to array of servers[{url}] (in swagger_helper.rb)')
+
+        swagger_doc[:servers] = { urls: [] }
+        swagger_doc[:schemes].each do |scheme|
+          swagger_doc[:servers][:urls] << scheme + '://' + swagger_doc[:host] + swagger_doc[:basePath]
+        end
+
+        swagger_doc.delete(:schemes)
+        swagger_doc.delete(:host)
+        swagger_doc.delete(:basePath)
+      end
+
+      def upgrade_oauth!(swagger_doc)
+        # find flow in securitySchemes (securityDefinitions will have been re-written)
+        schemes = swagger_doc.dig(:components, :securitySchemes)
+        return unless schemes&.any? { |_k, v| v.key?(:flow) }
+
+        schemes.each do |name, v|
+          next unless v.key?(:flow)
+
+          ActiveSupport::Deprecation.warn("Rswag::Specs: WARNING: securityDefinitions flow is replaced in OpenAPI3! Rename to components/securitySchemes/#{name}/flows[] (in swagger_helper.rb)")
+          flow = swagger_doc[:components][:securitySchemes][name].delete(:flow).to_s
+          if flow == 'accessCode'
+            ActiveSupport::Deprecation.warn("Rswag::Specs: WARNING: securityDefinitions accessCode is replaced in OpenAPI3! Rename to clientCredentials (in swagger_helper.rb)")
+            flow = 'authorizationCode'
+          end
+          if flow == 'application'
+            ActiveSupport::Deprecation.warn("Rswag::Specs: WARNING: securityDefinitions application is replaced in OpenAPI3! Rename to authorizationCode (in swagger_helper.rb)")
+            flow = 'clientCredentials'
+          end
+          flow_elements = swagger_doc[:components][:securitySchemes][name].except(:type).each_with_object({}) do |(k, _v), a|
+            a[k] = swagger_doc[:components][:securitySchemes][name].delete(k)
+          end
+          swagger_doc[:components][:securitySchemes][name].merge!(flows: { flow => flow_elements })
+        end
+      end
+
+      def remove_invalid_operation_keys!(value)
+        is_hash = value.is_a?(Hash)
+        value.delete(:consumes) if is_hash && value.dig(:consumes)
+        value.delete(:produces) if is_hash && value.dig(:produces)
+      end
     end
   end
 end

data/lib/tasks/rswag-specs_tasks.rake

@@ -1,18 +1,24 @@
+# frozen_string_literal: true
+
 require 'rspec/core/rake_task'
 
 namespace :rswag do
   namespace :specs do
-
     desc 'Generate Swagger JSON files from integration specs'
     RSpec::Core::RakeTask.new('swaggerize') do |t|
-      t.pattern = 'spec/requests/**/*_spec.rb, spec/api/**/*_spec.rb, spec/integration/**/*_spec.rb'
+      t.pattern = ENV.fetch(
+        'PATTERN',
+        'spec/requests/**/*_spec.rb, spec/api/**/*_spec.rb, spec/integration/**/*_spec.rb'
+      )
 
       # NOTE: rspec 2.x support
       if Rswag::Specs::RSPEC_VERSION > 2 && Rswag::Specs.config.swagger_dry_run
-        t.rspec_opts = [ '--format Rswag::Specs::SwaggerFormatter', '--dry-run', '--order defined' ]
+        t.rspec_opts = ['--format Rswag::Specs::SwaggerFormatter', '--dry-run', '--order defined']
       else
-        t.rspec_opts = [ '--format Rswag::Specs::SwaggerFormatter', '--order defined' ]
+        t.rspec_opts = ['--format Rswag::Specs::SwaggerFormatter', '--order defined']
       end
     end
   end
 end
+
+task rswag: ['rswag:specs:swaggerize']

metadata

@@ -1,14 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: rswag-specs
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.3.2
 platform: ruby
 authors:
 - Richie Morris
+- Greg Myers
+- Jay Danielian
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-16 00:00:00.000000000 Z
+date: 2021-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -19,7 +21,7 @@ dependencies:
         version: '3.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +31,7 @@ dependencies:
         version: '3.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
@@ -39,7 +41,7 @@ dependencies:
         version: '3.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -49,7 +51,7 @@ dependencies:
         version: '3.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6.1'
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: json-schema
   requirement: !ruby/object:Gem::Requirement
@@ -64,8 +66,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
-description: Simplify API integration testing with a succinct rspec DSL and generate
-  Swagger files directly from your rspecs
+description: 'Simplify API integration testing with a succinct rspec DSL and generate
+  OpenAPI specification files directly from your rspecs. More about the OpenAPI initiative
+  here: http://spec.openapis.org/'
 email:
 - domaindrivendev@gmail.com
 executables: []
@@ -91,7 +94,7 @@ files:
 - lib/rswag/specs/response_validator.rb
 - lib/rswag/specs/swagger_formatter.rb
 - lib/tasks/rswag-specs_tasks.rake
-homepage: https://github.com/domaindrivendev/rswag
+homepage: https://github.com/rswag/rswag
 licenses:
 - MIT
 metadata: {}
@@ -110,10 +113,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
-summary: A Swagger-based DSL for rspec-rails & accompanying rake task for generating
-  Swagger files
+summary: An OpenAPI-based (formerly called Swagger) DSL for rspec-rails & accompanying
+  rake task for generating OpenAPI specification files
 test_files: []