rswag-specs-2.1 2.9.1.ruby21

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5cce88ce3a4009e856838f9b55855ddacc6236c5079d6db1489f20a58a4a6044
+  data.tar.gz: 853c4742c3e67170fee783a499133124cb214d22754b077c00bb4340aed2dbc4
+SHA512:
+  metadata.gz: cc0b712f93dc012c75e7a1a7bc0adb371f7bc173e21f073670f1a140d8d4b8b214dad149ef1b4d01d17e79d0eb64e35611feadaf1ad910bc28dfb9dc21280d1b
+  data.tar.gz: d9e1beb5fce87764e603ffecf72a627eeb51edd89a398db741af2c84780d698fd14c2d142496418eabd209930fc4dc182a39b84c0e51534213669ab30471fdc9

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2015 domaindrivendev
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,23 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'rswag-specs'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks

data/lib/generators/rspec/USAGE

@@ -0,0 +1,9 @@
+Description:
+    This creates an RSpec request spec to define Swagger documentation for a
+    controller. It will create a test for each of the controller's methods.
+
+Example:
+    rails generate rspec:swagger V3::AccountsController
+
+    This will create:
+        spec/requests/v3/accounts_spec.rb

data/lib/generators/rspec/swagger_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'rswag/route_parser'
+require 'rails/generators'
+
+module Rspec
+  class SwaggerGenerator < ::Rails::Generators::NamedBase
+    source_root File.expand_path('templates', __dir__)
+    class_option :spec_path, type: :string, default: 'requests'
+
+    def setup
+      @routes = Rswag::RouteParser.new(controller_path).routes
+    end
+
+    def create_spec_file
+      template 'spec.rb', File.join('spec', options['spec_path'], "#{controller_path}_spec.rb")
+    end
+
+    private
+
+    def controller_path
+      file_path.chomp('_controller')
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+require 'swagger_helper'
+
+RSpec.describe '<%= controller_path %>', type: :request do
+<%  @routes.each do | template, path_item | %>
+  path '<%= template %>' do
+<%    unless path_item[:params].empty? -%>
+    # You'll want to customize the parameter types...
+<%      path_item[:params].each do |param| -%>
+    parameter name: '<%= param %>', in: :path, type: :string, description: '<%= param %>'
+<%      end -%>
+<%    end -%>
+<%    path_item[:actions].each do | action, details | %>
+    <%= action %>('<%= details[:summary] %>') do
+      response(200, 'successful') do
+<%      unless path_item[:params].empty? -%>
+<%        path_item[:params].each do |param| -%>
+        let(:<%= param %>) { '123' }
+<%        end -%>
+<%      end -%>
+
+        after do |example|
+          example.metadata[:response][:content] = {
+            'application/json' => {
+              example: JSON.parse(response.body, symbolize_names: true)
+            }
+          }
+        end
+        run_test!
+      end
+    end
+<%    end -%>
+  end
+<%  end -%>
+end

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

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

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

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

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.configure do |config|
+  # Specify a root folder where Swagger 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.swagger_root = Rails.root.join('swagger').to_s
+
+  # Define one or more Swagger 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 swagger_root
+  # By default, the operations defined in spec files are added to the first
+  # 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.yaml' => {
+      openapi: '3.0.1',
+      info: {
+        title: 'API V1',
+        version: 'v1'
+      },
+      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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Rswag
+  class RouteParser
+    attr_reader :controller
+
+    def initialize(controller)
+      @controller = controller
+    end
+
+    def routes
+      ::Rails.application.routes.routes.select do |route|
+        route.defaults[:controller] == controller
+      end.each_with_object({}) do |route, tree|
+        path = path_from(route)
+        verb = verb_from(route)
+        tree[path] ||= { params: params_from(route), actions: {} }
+        tree[path][:actions][verb] = { summary: summary_from(route) }
+        tree
+      end
+    end
+
+    private
+
+    def path_from(route)
+      route.path.spec.to_s
+        .chomp('(.:format)') # Ignore any format suffix
+        .gsub(/:([^\/.?]+)/, '{\1}') # Convert :id to {id}
+    end
+
+    def verb_from(route)
+      verb = route.verb
+      if verb.is_a? String
+        verb.downcase
+      else
+        verb.source.gsub(/[$^]/, '').downcase
+      end
+    end
+
+    def summary_from(route)
+      verb = route.requirements[:action]
+      noun = route.requirements[:controller].split('/').last.singularize
+
+      # Apply a few customizations to make things more readable
+      case verb
+      when 'index'
+        verb = 'list'
+        noun = noun.pluralize
+      when 'destroy'
+        verb = 'delete'
+      end
+
+      "#{verb} #{noun}"
+    end
+
+    def params_from(route)
+      route.segments - ['format']
+    end
+  end
+end

data/lib/rswag/specs/configuration.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Rswag
+  module Specs
+    class Configuration
+      def initialize(rspec_config)
+        @rspec_config = rspec_config
+      end
+
+      def swagger_root
+        @swagger_root ||= begin
+          if @rspec_config.swagger_root.nil?
+            raise ConfigurationError, 'No swagger_root provided. See swagger_helper.rb'
+          end
+
+          @rspec_config.swagger_root
+        end
+      end
+
+      def swagger_docs
+        @swagger_docs ||= begin
+          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
+
+      def swagger_dry_run
+        return @swagger_dry_run if defined? @swagger_dry_run
+        if ENV.key?('SWAGGER_DRY_RUN')
+          @rspec_config.swagger_dry_run = ENV['SWAGGER_DRY_RUN'] == '1'
+        end
+        @swagger_dry_run = @rspec_config.swagger_dry_run.nil? || @rspec_config.swagger_dry_run
+      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
+
+      def swagger_strict_schema_validation
+        @swagger_strict_schema_validation ||= (@rspec_config.swagger_strict_schema_validation || false)
+      end
+    end
+
+    class ConfigurationError < StandardError; end
+  end
+end

data/lib/rswag/specs/example_group_helpers.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'active_support'
+
+module Rswag
+  module Specs
+    module ExampleGroupHelpers
+      ActiveSupport::Deprecation.warn('Rswag::Specs: WARNING: Support for Ruby 2.6 will be dropped in v3.0') if RUBY_VERSION.start_with? '2.6'
+
+      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|
+        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|
+        define_method(attr_name) do |value|
+          metadata[:operation][attr_name] = value
+        end
+      end
+
+      # 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)
+        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|
+        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
+
+        if metadata.key?(:operation)
+          metadata[:operation][:parameters] ||= []
+          metadata[:operation][:parameters] << attributes
+        else
+          metadata[:path_item][:parameters] ||= []
+          metadata[:path_item][:parameters] << attributes
+        end
+      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
+      end
+
+      def response(code, description, metadata = {}, &block)
+        metadata[:response] = { code: code, description: description }
+        context(description, metadata, &block)
+      end
+
+      def schema(value)
+        metadata[:response][:schema] = value
+      end
+
+      def header(name, attributes)
+        metadata[:response][:headers] ||= {}
+
+        metadata[:response][:headers][name] = attributes
+      end
+
+      # NOTE: Similar to 'description', 'examples' need to handle the case when
+      # being invoked with no params to avoid overriding 'examples' method of
+      # 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)
+        # Todo - move initialization of metadata somewhere else.
+        if metadata[:response][:content].blank?
+          metadata[:response][:content] = {}
+        end
+
+        if metadata[:response][:content][mime].blank?
+          metadata[:response][:content][mime] = {}
+          metadata[:response][:content][mime][:examples] = {}
+        end
+
+        example_object = {
+          value: value,
+          summary: summary,
+          description: description
+        }.select { |_, v| v.present? }
+        # TODO, issue a warning if example is being overridden with the same key
+        metadata[:response][:content][mime][:examples].merge!(
+          { name.to_sym => example_object }
+        )
+      end
+
+      #
+      # Perform request and assert response matches swagger definitions
+      #
+      # @param options [Hash] options to pass to the `it` method
+      # @param &block [Proc] you can make additional assertions within that block
+      # @return [void]
+      def run_test!(**options, &block)
+        options[:rswag] = true unless options.key?(:rswag)
+
+        if RSPEC_VERSION < 3
+          ActiveSupport::Deprecation.warn('Rswag::Specs: WARNING: Support for RSpec 2.X will be dropped in v3.0')
+          before do
+            submit_request(example.metadata)
+          end
+
+          it "returns a #{metadata[:response][:code]} response", **options do
+            assert_response_matches_metadata(metadata)
+            block.call(response) if block_given?
+          end
+        else
+          before do |example|
+            submit_request(example.metadata)
+          end
+
+          it "returns a #{metadata[:response][:code]} response", **options do |example|
+            assert_response_matches_metadata(example.metadata, &block)
+            example.instance_exec(response, &block) if block_given?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rswag/specs/example_helpers.rb

@@ -0,0 +1,34 @@
+# 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)
+
+        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
+      end
+
+      def assert_response_matches_metadata(metadata)
+        ResponseValidator.new.validate!(metadata, response)
+      end
+    end
+  end
+end

data/lib/rswag/specs/extended_schema.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'json-schema'
+
+module Rswag
+  module Specs
+    class ExtendedSchema < JSON::Schema::Draft4
+      def initialize
+        super
+        @uri = URI.parse('http://tempuri.org/rswag/specs/extended_schema')
+        @names = ['http://tempuri.org/rswag/specs/extended_schema']
+      end
+
+      def validate(current_schema, data, *)
+        return if data.nil? && (current_schema.schema['nullable'] == true || current_schema.schema['x-nullable'] == true)
+
+        super
+      end
+    end
+
+    JSON::Validator.register_validator(ExtendedSchema.new)
+  end
+end

data/lib/rswag/specs/railtie.rb

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