rswag-specs 2.16.0 → 3.0.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8022f62493aff9272dc9e28dd243b7b4323dd34ebd7e6e2cd0c686ad5c04c252
-  data.tar.gz: 4926c9541ef625bd6acc1e1360b9c151a89b55dec7d3b8bb2cffb5f787d7546f
+  metadata.gz: c1204ba4bf6963e945006db21b5f303a1ebf305b7a282d68339133c0fff1a50f
+  data.tar.gz: 100e4b03500f6d3095c94cc16c73b43258f6e6a9935a1f518149272a81318c00
 SHA512:
-  metadata.gz: 6bd7e73cbface6b2aba3192e0ea7c4894834cfb18b1ad4a78a5661979d8674281d75d0f994de90319acdbe41136a5860675d9745c5de9ec9be0738775fa4c502
-  data.tar.gz: d641e842144cf173c6af4ab1ed17eeb72c95ad926f9c731afa426679ca8138b0467a151a8ecfcaa61bb18f2fb7f364043db99e58e2b96383c71cfd525daf76b8
+  metadata.gz: 2faf601571a0a755cc6900d40e3e402bc2ff68cdd9c83504562f000c562c9e3d6097fbfdaf5a6b3e7112d1f267324096d974b0cbec28fde6eede8df5a6beb6b3
+  data.tar.gz: daf1e344467c8fd82a07664264befcf28ac4a765be2973344f13e5d438ac5351cbb052b259c6846a24777c491437a13ba8c7d75405badeaeabc8d9e8efa79b48

data/Rakefile

@@ -1,4 +1,6 @@
 #!/usr/bin/env rake
+# frozen_string_literal: true
+
 begin
   require 'bundler/setup'
 rescue LoadError

data/lib/generators/rspec/{swagger_generator.rb → openapi_generator.rb}

@@ -4,7 +4,7 @@ require 'rswag/route_parser'
 require 'rails/generators'
 
 module Rspec
-  class SwaggerGenerator < ::Rails::Generators::NamedBase
+  class OpenapiGenerator < ::Rails::Generators::NamedBase
     source_root File.expand_path('templates', __dir__)
     class_option :spec_path, type: :string, default: 'requests'
 

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

@@ -1,4 +1,4 @@
-require 'swagger_helper'
+require 'openapi_helper'
 
 RSpec.describe '<%= controller_path %>', type: :request do
 <%  @routes.each do | template, path_item | %>

data/lib/generators/rswag/specs/install/USAGE

@@ -1,8 +1,8 @@
 Description:
-  Adds swagger_helper to enable Swagger DSL in integration specs
+  Adds openapi_helper to enable Swagger DSL in integration specs
 
 Example:
     rails generate rswag:specs:install
 
     This will create:
-        spec/swagger_helper.rb
+        spec/openapi_helper.rb

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

@@ -7,8 +7,8 @@ module Rswag
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path('templates', __dir__)
 
-      def add_swagger_helper
-        template('swagger_helper.rb', 'spec/swagger_helper.rb')
+      def add_openapi_helper
+        template('openapi_helper.rb', 'spec/openapi_helper.rb')
       end
     end
   end

data/lib/generators/rswag/specs/install/templates/{swagger_helper.rb → openapi_helper.rb}

@@ -3,19 +3,19 @@
 require 'rails_helper'
 
 RSpec.configure do |config|
-  # Specify a root folder where Swagger JSON files are generated
+  # Specify a root folder where OpenAPI JSON files are generated
   # NOTE: If you're using the rswag-api to serve API descriptions, you'll need
-  # to ensure that it's configured to serve Swagger from the same folder
-  config.openapi_root = Rails.root.join('swagger').to_s
+  # to ensure that it's configured to serve OpenAPI from the same folder
+  config.openapi_root = Rails.root.join('openapi').to_s
 
-  # Define one or more Swagger documents and provide global metadata for each one
+  # Define one or more OpenAPI documents and provide global metadata for each one
   # When you run the 'rswag:specs:swaggerize' rake task, the complete Swagger will
   # be generated at the provided relative path under openapi_root
   # By default, the operations defined in spec files are added to the first
   # document below. You can override this behavior by adding a openapi_spec tag to the
-  # the root example_group in your specs, e.g. describe '...', openapi_spec: 'v2/swagger.json'
+  # the root example_group in your specs, e.g. describe '...', openapi_spec: 'v2/openapi.json'
   config.openapi_specs = {
-    'v1/swagger.yaml' => {
+    'v1/openapi.yaml' => {
       openapi: '3.0.1',
       info: {
         title: 'API V1',
@@ -35,7 +35,7 @@ RSpec.configure do |config|
     }
   }
 
-  # Specify the format of the output Swagger file when running 'rswag:specs:swaggerize'.
+  # Specify the format of the output OpenAPI file when running 'rswag:specs:swaggerize'.
   # The openapi_specs 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'.

data/lib/rswag/route_parser.rb

@@ -24,8 +24,8 @@ module Rswag
 
     def path_from(route)
       route.path.spec.to_s
-        .chomp('(.:format)') # Ignore any format suffix
-        .gsub(/:([^\/.?]+)/, '{\1}') # Convert :id to {id}
+           .chomp('(.:format)') # Ignore any format suffix
+           .gsub(%r{:([^/.?]+)}, '{\1}') # Convert :id to {id}
     end
 
     def verb_from(route)

data/lib/rswag/specs/configuration.rb

@@ -9,13 +9,14 @@ module Rswag
 
       def openapi_root
         @openapi_root ||=
-          @rspec_config.openapi_root || raise(ConfigurationError, 'No openapi_root provided. See swagger_helper.rb')
+          @rspec_config.openapi_root || raise(ConfigurationError, 'No openapi_root provided. See openapi_helper.rb')
       end
 
       def openapi_specs
         @openapi_specs ||= begin
           if @rspec_config.openapi_specs.nil? || @rspec_config.openapi_specs.empty?
-            raise ConfigurationError, 'No openapi_specs defined. See swagger_helper.rb'
+            raise ConfigurationError,
+                  'No openapi_specs defined. See openapi_helper.rb'
           end
 
           @rspec_config.openapi_specs
@@ -24,9 +25,7 @@ module Rswag
 
       def rswag_dry_run
         @rswag_dry_run ||= begin
-          if ENV.key?('SWAGGER_DRY_RUN') || ENV.key?('RSWAG_DRY_RUN')
-            @rspec_config.rswag_dry_run = ENV['SWAGGER_DRY_RUN'] == '1' || ENV['RSWAG_DRY_RUN'] == '1'
-          end
+          @rspec_config.rswag_dry_run = ENV['RSWAG_DRY_RUN'] == '1' if ENV.key?('RSWAG_DRY_RUN')
 
           @rspec_config.rswag_dry_run.nil? || @rspec_config.rswag_dry_run
         end
@@ -38,8 +37,9 @@ module Rswag
             @rspec_config.openapi_format = :json
           end
 
-          unless [:json, :yaml].include?(@rspec_config.openapi_format)
-            raise ConfigurationError, "Unknown openapi_format '#{@rspec_config.openapi_format}'"
+          unless %i[json yaml].include?(@rspec_config.openapi_format)
+            raise ConfigurationError,
+                  "Unknown openapi_format '#{@rspec_config.openapi_format}'"
           end
 
           @rspec_config.openapi_format
@@ -53,15 +53,6 @@ module Rswag
         openapi_specs[name]
       end
 
-      def get_openapi_spec_version(name)
-        doc = get_openapi_spec(name)
-        doc[:openapi] || doc[:swagger]
-      end
-
-      def openapi_strict_schema_validation
-        @rspec_config.openapi_strict_schema_validation || false
-      end
-
       def openapi_all_properties_required
         @rspec_config.openapi_all_properties_required || false
       end

data/lib/rswag/specs/example_group_helpers.rb

@@ -5,19 +5,19 @@ require 'active_support'
 module Rswag
   module Specs
     module ExampleGroupHelpers
-      def path(template, metadata = {}, &block)
+      def path(template, *tags, **metadata, &block)
         metadata[:path_item] = { template: template }
-        describe(template, metadata, &block)
+        describe(template, *tags, **metadata, &block)
       end
 
-      [:get, :post, :patch, :put, :delete, :head, :options, :trace].each do |verb|
-        define_method(verb) do |summary, **metadata, &block|
+      %i[get post patch put delete head options trace].each do |verb|
+        define_method(verb) do |summary, *tags, **metadata, &block|
           api_metadata = { operation: { verb: verb, summary: summary } }.deep_merge(metadata)
-          describe(verb, **api_metadata, &block)
+          describe(verb, *tags, **api_metadata, &block)
         end
       end
 
-      [:operationId, :deprecated, :security].each do |attr_name|
+      %i[operationId deprecated security].each do |attr_name|
         define_method(attr_name) do |value|
           metadata[:operation][attr_name] = value
         end
@@ -33,16 +33,14 @@ module Rswag
       end
 
       # These are array properties - note the splat operator
-      [:tags, :consumes, :produces, :schemes].each do |attr_name|
+      %i[tags consumes produces schemes].each do |attr_name|
         define_method(attr_name) do |*value|
           metadata[:operation][attr_name] = value
         end
       end
 
       def parameter(attributes)
-        if attributes[:in] && attributes[:in].to_sym == :path
-          attributes[:required] = true
-        end
+        attributes[:required] = true if attributes[:in] && attributes[:in].to_sym == :path
 
         if metadata.key?(:operation)
           metadata[:operation][:parameters] ||= []
@@ -54,19 +52,20 @@ module Rswag
       end
 
       def request_body_example(value:, summary: nil, name: nil)
-        if metadata.key?(:operation)
-          metadata[:operation][:request_examples] ||= []
-          example = { value: value }
-          example[:summary] = summary if summary
-          # We need the examples to have a unique name for a set of examples, so just make the name the length if one isn't provided.
-          example[:name] = name || metadata[:operation][:request_examples].length()
-          metadata[:operation][:request_examples] << example
-        end
+        return unless metadata.key?(:operation)
+
+        metadata[:operation][:request_examples] ||= []
+        example = { value: value }
+        example[:summary] = summary if summary
+        # We need the examples to have a unique name for a set of examples,
+        # so just make the name the length if one isn't provided.
+        example[:name] = name || metadata[:operation][:request_examples].length
+        metadata[:operation][:request_examples] << example
       end
 
-      def response(code, description, metadata = {}, &block)
+      def response(code, description, *tags, **metadata, &block)
         metadata[:response] = { code: code, description: description }
-        context(description, metadata, &block)
+        context(description, *tags, **metadata, &block)
       end
 
       def schema(value)
@@ -84,17 +83,16 @@ module Rswag
       # rspec-core ExampleGroup
       def examples(examples = nil)
         return super() if examples.nil?
+
         # should we add a deprecation warning?
         examples.each_with_index do |(mime, example_object), index|
           example(mime, "example_#{index}", example_object)
         end
       end
 
-      def example(mime, name, value, summary=nil, description=nil)
+      def example(mime, name, value, summary = nil, description = nil)
         # Todo - move initialization of metadata somewhere else.
-        if metadata[:response][:content].blank?
-          metadata[:response][:content] = {}
-        end
+        metadata[:response][:content] = {} if metadata[:response][:content].blank?
 
         if metadata[:response][:content][mime].blank?
           metadata[:response][:content][mime] = {}
@@ -126,24 +124,13 @@ module Rswag
 
         description ||= "returns a #{metadata[:response][:code]} response"
 
-        if RSPEC_VERSION < 3
-          before do
-            submit_request(example.metadata)
-          end
+        before do |example|
+          submit_request(example.metadata)
+        end
 
-          it description, *args, **options do
-            assert_response_matches_metadata(metadata)
-            block.call(response) if block_given?
-          end
-        else
-          before do |example|
-            submit_request(example.metadata)
-          end
-
-          it description, *args, **options do |example|
-            assert_response_matches_metadata(example.metadata, &block)
-            example.instance_exec(response, &block) if block_given?
-          end
+        it description, *args, **options do |example|
+          assert_response_matches_metadata(example.metadata, &block)
+          example.instance_exec(response, &block) if block_given?
         end
       end
     end

data/lib/rswag/specs/example_helpers.rb

@@ -7,23 +7,14 @@ module Rswag
   module Specs
     module ExampleHelpers
       def submit_request(metadata)
-        request = RequestFactory.new.build_request(metadata, self)
+        request = RequestFactory.new(metadata, self).build_request
 
-        if RAILS_VERSION < 5
-          send(
-            request[:verb],
-            request[:path],
-            request[:payload],
-            request[:headers]
-          )
-        else
-          send(
-            request[:verb],
-            request[:path],
-            params: request[:payload],
-            headers: request[:headers]
-          )
-        end
+        send(
+          request[:verb],
+          request[:path],
+          params: request[:payload],
+          headers: request[:headers]
+        )
       end
 
       def assert_response_matches_metadata(metadata)

data/lib/rswag/specs/extended_schema.rb

@@ -12,7 +12,9 @@ module Rswag
       end
 
       def validate(current_schema, data, *)
-        return if data.nil? && (current_schema.schema['nullable'] == true || current_schema.schema['x-nullable'] == true)
+        if data.nil? && (current_schema.schema['nullable'] == true || current_schema.schema['x-nullable'] == true)
+          return
+        end
 
         super
       end

data/lib/rswag/specs/openapi_formatter.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/deep_merge'
+require 'rspec/core/formatters/base_text_formatter'
+require 'openapi_helper'
+
+module Rswag
+  module Specs
+    class OpenapiFormatter < ::RSpec::Core::Formatters::BaseTextFormatter
+      ::RSpec::Core::Formatters.register self, :example_group_finished, :stop
+
+      def initialize(output, config = Rswag::Specs.config)
+        @output = output
+        @config = config
+
+        @output.puts 'Generating OpenAPI spec...'
+      end
+
+      def example_group_finished(notification)
+        metadata = notification.group.metadata
+        # metadata[:document] has to be explicitly false to skip generating docs
+        return if metadata[:document] == false
+        return unless metadata.key?(:response)
+
+        openapi_spec = @config.get_openapi_spec(metadata[:openapi_spec])
+        raise ConfigurationError, 'Unsupported OpenAPI version' unless doc_version(openapi_spec).start_with?('3')
+
+        # 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_response_produces!(openapi_spec, metadata)
+
+        openapi_spec.deep_merge!(metadata_to_openapi(metadata))
+      end
+
+      def stop(_notification = nil)
+        @config.openapi_specs.each do |url_path, doc|
+          parse_parameters(doc)
+
+          file_path = File.join(@config.openapi_root, url_path)
+          dirname = File.dirname(file_path)
+          FileUtils.mkdir_p dirname unless File.exist?(dirname)
+
+          File.open(file_path, 'w') do |file|
+            file.write(pretty_generate(doc))
+          end
+
+          @output.puts "OpenAPI doc generated at #{file_path}"
+        end
+      end
+
+      private
+
+      def pretty_generate(doc)
+        if @config.openapi_format == :yaml
+          clean_doc = yaml_prepare(doc)
+          YAML.dump(clean_doc)
+        else # config errors are thrown in 'def openapi_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_openapi(metadata)
+        response_code = metadata[:response][:code]
+        response = metadata[:response].reject { |k, _v| k == :code }
+
+        verb = metadata[:operation][:verb]
+        operation = metadata[:operation]
+                    .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 }
+                    .merge(verb => operation)
+
+        { paths: { path_template => path_item } }
+      end
+
+      def doc_version(doc)
+        doc[:openapi]
+      end
+
+      def upgrade_response_produces!(openapi_spec, metadata)
+        # Accept header
+        mime_list = Array(metadata[:operation][:produces] || openapi_spec[: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] ||= {}
+        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.values).each do |node|
+          if node && node[:type] && node[:schema].nil?
+            node[:schema] = { type: node[:type] }
+            node.delete(:type)
+          end
+        end
+      end
+
+      def remove_invalid_operation_keys!(value)
+        return unless value.is_a?(Hash)
+
+        value.delete(:consumes) if value[:consumes]
+        value.delete(:produces) if value[:produces]
+        value.delete(:request_examples) if value[:request_examples]
+      end
+
+      def parse_parameters(doc)
+        doc[:paths]&.each_pair do |_k, path|
+          path.each_pair do |_verb, endpoint|
+            is_hash = endpoint.is_a?(Hash)
+            if is_hash && endpoint[:parameters]
+              mime_list = endpoint[:consumes] || doc[:consumes]
+              parse_endpoint(endpoint, mime_list)
+            end
+            remove_invalid_operation_keys!(endpoint)
+          end
+        end
+      end
+
+      def parse_endpoint(endpoint, mime_list)
+        parameters = endpoint[:parameters]
+
+        # Parse any parameters
+        parameters.each do |parameter|
+          set_parameter_schema(parameter)
+          convert_file_parameter(parameter)
+          parse_enum(parameter)
+        end
+
+        # Parse parameters that are body parameters:
+        parameters.select { |p| parameter_in_form_data_or_body?(p) }.each do |parameter|
+          parse_form_data_or_body_parameter(endpoint, parameter, mime_list)
+          parameters.delete(parameter) # "consume" parameters that will end up in response body
+        end
+
+        # Remove blank schemas - todo: refactor to not add in the first place
+        parameters.each { |p| p.delete(:schema) if p[:schema].blank? }
+      end
+
+      def set_parameter_schema(parameter)
+        # It might be that the schema has a required attribute as a boolean, but it must be an array, hence remove it
+        # and simply mark the parameter as required, which will be processed later.
+        parameter[:schema] ||= {}
+        if parameter[:schema].key?(:required) && parameter[:schema][:required] == true
+          parameter[:required] =
+            parameter[:schema].delete(:required)
+        end
+        #  Also parameters currently can be defined with a datatype (`type:`)
+        #  but this should be in `schema:` in the output.
+        parameter[:schema][:type] = parameter.delete(:type) if parameter.key?(:type)
+      end
+
+      def parameter_in_form_data_or_body?(p)
+        p[:in] == :formData || parameter_in_body?(p)
+      end
+
+      def parameter_in_body?(p)
+        p[:in] == :body
+      end
+
+      def parse_form_data_or_body_parameter(endpoint, parameter, mime_list)
+        unless mime_list
+          raise ConfigurationError,
+                'A body or form data parameters are specified without a Media Type for the content'
+        end
+
+        # Only add requestBody if there are any body parameters and not already defined
+        add_request_body(endpoint)
+
+        # If a description is provided for the parameter, it should be moved to the schema description
+        desc = parameter.delete(:description)
+        parameter[:schema][:description] = desc if desc
+
+        mime_list.each do |mime|
+          endpoint[:requestBody][:content][mime] ||= {}
+          mime_config = endpoint[:requestBody][:content][mime]
+
+          # Only parse parameters if there has not already been a reference object set. Ie if a `in: :body` parameter
+          # has been seen already `schema` is defined, or if formData is being used then ensure we have a `properties`
+          # key in schema.
+          next unless mime_config[:schema].nil? || mime_config.dig(:schema, :properties)
+
+          set_mime_config(mime_config, parameter)
+          set_mime_examples(mime_config, endpoint)
+          set_request_body_required(mime_config, endpoint, parameter)
+        end
+      end
+
+      def add_request_body(endpoint)
+        return if endpoint.dig(:requestBody, :content)
+
+        endpoint[:requestBody] = { content: {} }
+      end
+
+      def set_request_body_required(mime_config, endpoint, parameter)
+        return unless parameter[:required]
+
+        # FIXME: If any are `required` then the body is set to `required` but this assumption may not hold in reality as
+        # you could have optional body, but if body is provided then some properties are required.
+        endpoint[:requestBody][:required] = true
+
+        return if parameter_in_body?(parameter)
+
+        if parameter[:name]
+          mime_config[:schema][:required] ||= []
+          mime_config[:schema][:required] << parameter[:name].to_s
+        else
+          mime_config[:schema][:required] = true
+        end
+      end
+
+      def convert_file_parameter(parameter)
+        return unless parameter[:schema][:type] == :file
+
+        parameter[:schema][:type] = :string
+        parameter[:schema][:format] = :binary
+      end
+
+      def set_mime_config(mime_config, parameter)
+        schema_with_form_properties = parameter[:name] && !parameter_in_body?(parameter)
+        mime_config[:schema] ||= schema_with_form_properties ? { type: :object, properties: {} } : parameter[:schema]
+        return unless schema_with_form_properties
+
+        mime_config[:schema][:properties][parameter[:name]] = parameter[:schema]
+        set_mime_encoding(mime_config, parameter)
+      end
+
+      def set_mime_encoding(mime_config, parameter)
+        return unless parameter[:encoding]
+
+        encoding = parameter[:encoding].dup
+        encoding[:contentType] = encoding[:contentType].join(',') if encoding[:contentType].is_a?(Array)
+        mime_config[:encoding] ||= {}
+        mime_config[:encoding][parameter[:name]] = encoding
+      end
+
+      def set_mime_examples(mime_config, endpoint)
+        examples = endpoint[:request_examples]
+        return unless examples
+
+        examples.each do |example|
+          mime_config[:examples] ||= {}
+          mime_config[:examples][example[:name]] = {
+            summary: example[:summary] || endpoint[:summary],
+            value: example[:value]
+          }
+        end
+      end
+
+      def parse_enum(parameter)
+        return unless parameter.key?(:enum)
+
+        enum = parameter.delete(:enum)
+        parameter[:schema] ||= {}
+        parameter[:schema][:enum] = enum.is_a?(Hash) ? enum.keys.map(&:to_s) : enum
+        parameter[:description] = generate_enum_description(parameter, enum) if enum.is_a?(Hash)
+      end
+
+      def generate_enum_description(param, enum)
+        enum_description = "#{param[:description]}:\n "
+        enum.each do |k, v|
+          enum_description += "* `#{k}` #{v}\n "
+        end
+        enum_description
+      end
+    end
+  end
+end

data/lib/rswag/specs/railtie.rb

@@ -8,13 +8,7 @@ module Rswag
       end
 
       generators do
-        require 'generators/rspec/swagger_generator'
-      end
-
-      initializer 'rswag-specs.deprecator' do |app|
-        if app.respond_to?(:deprecators)
-          app.deprecators[:rswag_specs] = Rswag::Specs.deprecator
-        end
+        require 'generators/rspec/openapi_generator'
       end
     end
   end