rspec_api_documentation 4.9.0 → 6.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 16b47e6bedc1c86cc5e418233eca8b80d16b5628
-  data.tar.gz: e1da890616a2fa4cf6a8ff8c44eff5977abc32f6
+  metadata.gz: 8e1f18cb4e1bbf1939b21e8a4bdeb0ca17aae8f2
+  data.tar.gz: 98c99830570aad0754d38787cbe528cde8d795f5
 SHA512:
-  metadata.gz: c16d4338f5d6e06f1c913a951c1370b31f2e6c85a6aef38a593d5fbd332226ad99c9fae76207e9bed5089500010a5b588a123e0354cdef25d057cbc0483a1933
-  data.tar.gz: 03ef3fbf5306d2951fa6f3b82f08e2679306069e791ef9bf5d30f58693dbb83528bb78009821cc4b26fb1da166c33620c1e5d327c9d91f8008bd45afa93eead4
+  metadata.gz: 000471a180aa638ee4ac2852410f4202f210d3694118a0aafb0b31a7dde2d61baeb1e40fcc45cdfaf149962479de12390ee88096b338e7a6ad979436468ca83e
+  data.tar.gz: b2bb72596bdbe8896243c14b69a022e8c820e57fba621c45518ccea38b304c08b165d8b2e910644bbf96af256c989157950785654f91dd554b6a6a7042a85782

data/lib/rspec_api_documentation/api_documentation.rb

@@ -1,3 +1,5 @@
+require 'rspec_api_documentation/writers/json_iodocs_writer'
+
 module RspecApiDocumentation
   class ApiDocumentation
     attr_reader :configuration, :index

data/lib/rspec_api_documentation/client_base.rb

@@ -96,14 +96,14 @@ module RspecApiDocumentation
     end
 
     def clean_out_uploaded_data(params, request_body)
-      params.each do |_, value|
-        if value.is_a?(Hash)
-          if value.has_key?(:tempfile)
-            data = value[:tempfile].read
-            request_body = request_body.gsub(data, "[uploaded data]")
-          else
-            request_body = clean_out_uploaded_data(value,request_body)
-          end
+      params.each do |value|
+        if [Hash, Array].member? value.class
+          request_body = if value.respond_to?(:has_key?) && value.has_key?(:tempfile)
+                           data = value[:tempfile].read
+                           request_body.gsub(data, "[uploaded data]")
+                         else
+                           clean_out_uploaded_data(value, request_body)
+                         end
         end
       end
       request_body

data/lib/rspec_api_documentation/configuration.rb

@@ -51,6 +51,14 @@ module RspecApiDocumentation
       end
     end
 
+    add_setting :configurations_dir, :default => lambda { |config|
+      if defined?(Rails)
+        Rails.root.join('doc', 'configurations', 'api')
+      else
+        Pathname.new('doc/configurations/api')
+      end
+    }
+
     add_setting :docs_dir, :default => lambda { |config|
       if defined?(Rails)
         Rails.root.join("doc", "api")
@@ -75,6 +83,7 @@ module RspecApiDocumentation
     add_setting :curl_host, :default => nil
     add_setting :keep_source_order, :default => false
     add_setting :api_name, :default => "API Documentation"
+    add_setting :api_explanation, :default => nil
     add_setting :io_docs_protocol, :default => "http"
     add_setting :request_headers_to_include, :default => nil
     add_setting :response_headers_to_include, :default => nil
@@ -109,7 +118,7 @@ module RspecApiDocumentation
     # See RspecApiDocumentation::DSL::Endpoint#do_request
     add_setting :response_body_formatter, default: Proc.new { |_, _|
       Proc.new do |content_type, response_body|
-        if content_type =~ /application\/json/
+        if content_type =~ /application\/.*json/
           JSON.pretty_generate(JSON.parse(response_body))
         else
           response_body
@@ -118,6 +127,8 @@ module RspecApiDocumentation
     }
 
     def client_method=(new_client_method)
+      return if new_client_method == client_method
+
       RspecApiDocumentation::DSL::Resource.module_eval <<-RUBY
         alias :#{new_client_method} #{client_method}
         undef #{client_method}

data/lib/rspec_api_documentation/curl.rb

@@ -16,7 +16,7 @@ module RspecApiDocumentation
     end
 
     def get
-      "curl \"#{url}#{get_data}\" -X GET #{headers}"
+      "curl -g \"#{url}#{get_data}\" -X GET #{headers}"
     end
 
     def head
@@ -69,7 +69,12 @@ module RspecApiDocumentation
     end
 
     def format_full_header(header, value)
-      formatted_value = value ? value.gsub(/"/, "\\\"") : ''
+      formatted_value = if value.is_a?(Numeric)
+        value
+      else
+        value ? value.gsub(/"/, "\\\"") : ''
+      end
+
       "#{format_header(header)}: #{formatted_value}"
     end
 

data/lib/rspec_api_documentation/dsl/endpoint/params.rb

@@ -13,11 +13,27 @@ module RspecApiDocumentation
         end
 
         def call
-          parameters = example.metadata.fetch(:parameters, {}).inject({}) do |hash, param|
+          set_param = -> hash, param {
             SetParam.new(self, hash, param).call
+          }
+
+          example.metadata.fetch(:parameters, {}).inject({}, &set_param)
+            .deep_merge(
+              example.metadata.fetch(:attributes, {}).inject({}, &set_param)
+            ).deep_merge(extra_params)
+        end
+
+        def extended
+          example.metadata.fetch(:parameters, {}).map do |param|
+            p = Marshal.load(Marshal.dump(param))
+            p[:value] = SetParam.new(self, nil, p).value
+            unless p[:value]
+              cur = extra_params
+              [*p[:scope]].each { |scope| cur = cur && (cur[scope.to_sym] || cur[scope.to_s]) }
+              p[:value] = cur && (cur[p[:name].to_s] || cur[p[:name].to_sym])
+            end
+            p
           end
-          parameters.deep_merge!(extra_params)
-          parameters
         end
 
       private

data/lib/rspec_api_documentation/dsl/endpoint/set_param.rb

@@ -15,6 +15,10 @@ module RspecApiDocumentation
           hash.deep_merge build_param_hash(key_scope || [key])
         end
 
+        def value
+          example_group.send(method_name) if method_name
+        end
+
       private
 
         attr_reader :parent, :hash, :param
@@ -36,6 +40,10 @@ module RspecApiDocumentation
           param[:method]
         end
 
+        def set_value
+          param[:value]
+        end
+
         def path_name
           scoped_key || key
         end
@@ -45,15 +53,20 @@ module RspecApiDocumentation
         end
 
         def method_name
-          @method_name ||= begin
-            [custom_method_name, scoped_key, key].find do |name|
-              name && example_group.respond_to?(name)
-            end
+          if custom_method_name
+            custom_method_name if example_group.respond_to?(custom_method_name)
+          elsif scoped_key && example_group.respond_to?(scoped_key)
+            scoped_key
+          elsif key && example_group.respond_to?(key)
+            key
+          elsif key && set_value
+            key
           end
         end
 
         def build_param_hash(keys)
-          value = keys[1] ? build_param_hash(keys[1..-1]) : example_group.send(method_name)
+          value = param[:value] if param.has_key?(:value)
+          value ||= keys[1] ? build_param_hash(keys[1..-1]) : example_group.send(method_name)
           { keys[0].to_s => value }
         end
       end

data/lib/rspec_api_documentation/dsl/endpoint.rb

@@ -9,6 +9,8 @@ module RspecApiDocumentation::DSL
     extend ActiveSupport::Concern
     include Rack::Test::Utils
 
+    URL_PARAMS_REGEX = /[:\{](\w+)\}?/.freeze
+
     delegate :response_headers, :response_status, :response_body, :to => :rspec_api_documentation_client
 
     module ClassMethods
@@ -36,6 +38,9 @@ module RspecApiDocumentation::DSL
       params_or_body = nil
       path_or_query = path
 
+      extended_parameters
+      extract_route_parameters!
+
       if http_method == :get && !query_string.blank?
         path_or_query += "?#{query_string}"
       else
@@ -72,6 +77,36 @@ module RspecApiDocumentation::DSL
       example.metadata[:headers][name] = value
     end
 
+    def authentication(type, value, opts = {})
+      name, new_opts =
+        case type
+        when :basic then ['Authorization', opts.merge(type: type)]
+        when :apiKey then [opts[:name], opts.merge(type: type, in: :header)]
+        else raise 'Not supported type for authentication'
+        end
+      header(name, value)
+      example.metadata[:authentications] ||= {}
+      example.metadata[:authentications][name] = new_opts
+    end
+
+    def extract_route_parameters!
+      example.metadata[:route].gsub(URL_PARAMS_REGEX) do |match|
+        value =
+          if extra_params.keys.include?($1)
+            extra_params[$1]
+          elsif respond_to?($1)
+            send($1)
+          else
+            match
+          end
+        extended_parameters << {name: match[1..-1], value: value, in: :path}
+      end
+    end
+
+    def extended_parameters
+      example.metadata[:extended_parameters] ||= Params.new(self, example, extra_params).extended
+    end
+
     def headers
       return unless example.metadata[:headers]
       example.metadata[:headers].inject({}) do |hash, (header, value)|
@@ -96,8 +131,16 @@ module RspecApiDocumentation::DSL
       rspec_api_documentation_client.status
     end
 
+    def in_path?(param)
+      path_params.include?(param)
+    end
+
+    def path_params
+      example.metadata[:route].scan(URL_PARAMS_REGEX).flatten
+    end
+
     def path
-      example.metadata[:route].gsub(/:(\w+)/) do |match|
+      example.metadata[:route].gsub(URL_PARAMS_REGEX) do |match|
         if extra_params.keys.include?($1)
           delete_extra_param($1)
         elsif respond_to?($1)
@@ -134,6 +177,5 @@ module RspecApiDocumentation::DSL
     def delete_extra_param(key)
       @extra_params.delete(key.to_sym) || @extra_params.delete(key.to_s)
     end
-
   end
 end

data/lib/rspec_api_documentation/dsl/resource.rb

@@ -8,7 +8,12 @@ module RspecApiDocumentation::DSL
         define_method method do |*args, &block|
           options = args.extract_options!
           options[:method] = method
-          options[:route] = args.first
+          if metadata[:route_uri]
+            options[:route] = metadata[:route_uri]
+            options[:action_name] = args.first
+          else
+            options[:route] = args.first
+          end
           options[:api_doc_dsl] = :endpoint
           args.push(options)
           args[0] = "#{method.to_s.upcase} #{args[0]}"
@@ -38,10 +43,25 @@ module RspecApiDocumentation::DSL
         context(*args, &block)
       end
 
+      def route(*args, &block)
+        raise "You must define the route URI"  if args[0].blank?
+        raise "You must define the route name" if args[1].blank?
+        options = args.extract_options!
+        options[:route_uri] = args[0].gsub(/\{.*\}/, "")
+        options[:route_optionals] = (optionals = args[0].match(/(\{.*\})/) and optionals[-1])
+        options[:route_name] = args[1]
+        args.push(options)
+        context(*args, &block)
+      end
+
       def parameter(name, *args)
         parameters.push(field_specification(name, *args))
       end
 
+      def attribute(name, *args)
+        attributes.push(field_specification(name, *args))
+      end
+
       def response_field(name, *args)
         response_fields.push(field_specification(name, *args))
       end
@@ -50,6 +70,25 @@ module RspecApiDocumentation::DSL
         headers[name] = value
       end
 
+      def authentication(type, value, opts = {})
+        name, new_opts =
+          case type
+          when :basic then ['Authorization', opts.merge(type: type)]
+          when :apiKey then [opts[:name], opts.merge(type: type, in: :header)]
+          else raise 'Not supported type for authentication'
+          end
+        header(name, value)
+        authentications[name] = new_opts
+      end
+
+      def route_summary(text)
+        safe_metadata(:route_summary, text)
+      end
+
+      def route_description(text)
+        safe_metadata(:route_description, text)
+      end
+
       def explanation(text)
         safe_metadata(:resource_explanation, text)
       end
@@ -75,6 +114,10 @@ module RspecApiDocumentation::DSL
         safe_metadata(:parameters, [])
       end
 
+      def attributes
+        safe_metadata(:attributes, [])
+      end
+
       def response_fields
         safe_metadata(:response_fields, [])
       end
@@ -83,6 +126,10 @@ module RspecApiDocumentation::DSL
         safe_metadata(:headers, {})
       end
 
+      def authentications
+        safe_metadata(:authentications, {})
+      end
+
       def parameter_keys
         parameters.map { |param| param[:name] }
       end

data/lib/rspec_api_documentation/dsl.rb

@@ -21,7 +21,7 @@ module RspecApiDocumentation
       options = args.last.is_a?(Hash) ? args.pop : {}
       options[:api_doc_dsl] = :resource
       options[:resource_name] = args.first.to_s
-      options[:document] ||= :all
+      options[:document] = :all unless options.key?(:document)
       args.push(options)
       describe(*args, &block)
     end

data/lib/rspec_api_documentation/example.rb

@@ -38,6 +38,10 @@ module RspecApiDocumentation
       respond_to?(:parameters) && parameters.present?
     end
 
+    def has_attributes?
+      respond_to?(:attributes) && attributes.present?
+    end
+
     def has_response_fields?
       respond_to?(:response_fields) && response_fields.present?
     end

data/lib/rspec_api_documentation/open_api/contact.rb

@@ -0,0 +1,9 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Contact < Node
+      add_setting :name, :default => 'API Support'
+      add_setting :url, :default => 'http://www.open-api.io/support'
+      add_setting :email, :default => 'support@open-api.io'
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/example.rb

@@ -0,0 +1,7 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Example < Node
+      CHILD_CLASS = true
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/header.rb

@@ -0,0 +1,12 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Header < Node
+      add_setting :description, :default => ''
+      add_setting :type, :required => true, :default => lambda { |header|
+        Helper.extract_type(header.public_send('x-example-value'))
+      }
+      add_setting :format
+      add_setting 'x-example-value'
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/headers.rb

@@ -0,0 +1,7 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Headers < Node
+      CHILD_CLASS = Header
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/helper.rb

@@ -0,0 +1,29 @@
+module RspecApiDocumentation
+  module OpenApi
+    module Helper
+      module_function
+
+      def extract_type(value)
+        case value
+        when Rack::Test::UploadedFile then :file
+        when Array then :array
+        when Hash then :object
+        when TrueClass, FalseClass then :boolean
+        when Integer then :integer
+        when Float then :number
+        else :string
+        end
+      end
+
+      def extract_items(value, opts = {})
+        result = {type: extract_type(value)}
+        if result[:type] == :array
+          result[:items] = extract_items(value[0], opts)
+        else
+          opts.each { |k, v| result[k] = v if v }
+        end
+        result
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/info.rb

@@ -0,0 +1,12 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Info < Node
+      add_setting :title, :default => 'OpenAPI Specification', :required => true
+      add_setting :description, :default => 'This is a sample server Petstore server.'
+      add_setting :termsOfService, :default => 'http://open-api.io/terms/'
+      add_setting :contact, :default => Contact.new, :schema => Contact
+      add_setting :license, :default => License.new, :schema => License
+      add_setting :version, :default => '1.0.0', :required => true
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/license.rb

@@ -0,0 +1,8 @@
+module RspecApiDocumentation
+  module OpenApi
+    class License < Node
+      add_setting :name, :default => 'Apache 2.0', :required => true
+      add_setting :url, :default => 'http://www.apache.org/licenses/LICENSE-2.0.html'
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/node.rb

@@ -0,0 +1,112 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Node
+      # this is used to define class of incoming option attribute
+      # If +false+ then do not create new setting
+      # If +true+ then create new setting with raw passed value
+      # If RspecApiDocumentation::OpenApi::Node then create new setting and wrap it in this class
+      CHILD_CLASS = false
+
+      # This attribute allow us to hide some of children through configuration file
+      attr_accessor :hide
+
+      def self.add_setting(name, opts = {})
+        class_settings << name
+
+        define_method("#{name}_schema") { opts[:schema] || NilClass }
+        define_method("#{name}=") { |value| settings[name] = value }
+        define_method("#{name}") do
+          if settings.has_key?(name)
+            settings[name]
+          elsif !opts[:default].nil?
+            if opts[:default].respond_to?(:call)
+              opts[:default].call(self)
+            else
+              opts[:default]
+            end
+          elsif opts[:required]
+            raise "setting: #{name} required in #{self}"
+          end
+        end
+      end
+
+      def initialize(opts = {})
+        return unless opts
+
+        opts.each do |name, value|
+          if name.to_s == 'hide'
+            self.hide = value
+          elsif self.class::CHILD_CLASS
+            add_setting name, :value => self.class::CHILD_CLASS === true ? value : self.class::CHILD_CLASS.new(value)
+          elsif setting_exist?(name.to_sym)
+            schema = setting_schema(name)
+            converted =
+              case
+              when schema.is_a?(Array) && schema[0] <= Node then value.map { |v| v.is_a?(schema[0]) ? v : schema[0].new(v) }
+              when schema <= Node then value.is_a?(schema) ? value : schema.new(value)
+              else
+                value
+              end
+            assign_setting(name, converted)
+          else
+            public_send("#{name}=", value) if respond_to?("#{name}=")
+          end
+        end
+      end
+
+      def assign_setting(name, value); public_send("#{name}=", value) unless value.nil? end
+      def safe_assign_setting(name, value); assign_setting(name, value) unless settings.has_key?(name) end
+      def setting(name); public_send(name) end
+      def setting_schema(name); public_send("#{name}_schema") end
+      def setting_exist?(name); existing_settings.include?(name) end
+      def existing_settings; self.class.class_settings + instance_settings end
+
+      def add_setting(name, opts = {})
+        return false if setting_exist?(name)
+
+        instance_settings << name
+
+        settings[name] = opts[:value] if opts[:value]
+
+        define_singleton_method("#{name}_schema") { opts[:schema] || NilClass }
+        define_singleton_method("#{name}=") { |value| settings[name] = value }
+        define_singleton_method("#{name}") do
+          if settings.has_key?(name)
+            settings[name]
+          elsif !opts[:default].nil?
+            if opts[:default].respond_to?(:call)
+              opts[:default].call(self)
+            else
+              opts[:default]
+            end
+          elsif opts[:required]
+            raise "setting: #{name} required in #{self}"
+          end
+        end
+      end
+
+      def as_json
+        existing_settings.inject({}) do |hash, name|
+          value = setting(name)
+          case
+          when value.is_a?(Node)
+            hash[name] = value.as_json unless value.hide
+          when value.is_a?(Array) && value[0].is_a?(Node)
+            tmp = value.select { |v| !v.hide }.map { |v| v.as_json }
+            hash[name] = tmp unless tmp.empty?
+          else
+            hash[name] = value
+          end unless value.nil?
+
+          hash
+        end
+      end
+
+      private
+
+      def settings; @settings ||= {} end
+      def instance_settings; @instance_settings ||= [] end
+      def self.class_settings; @class_settings ||= [] end
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/operation.rb

@@ -0,0 +1,18 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Operation < Node
+      add_setting :tags, :default => []
+      add_setting :summary
+      add_setting :description, :default => ''
+      add_setting :externalDocs
+      add_setting :operationId
+      add_setting :consumes
+      add_setting :produces
+      add_setting :parameters, :default => [], :schema => [Parameter]
+      add_setting :responses, :required => true, :schema => Responses
+      add_setting :schemes
+      add_setting :deprecated, :default => false
+      add_setting :security
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/parameter.rb

@@ -0,0 +1,33 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Parameter < Node
+      # Required to write example values to description of parameter when option `with_example: true` is provided
+      attr_accessor :value
+      attr_accessor :with_example
+
+      add_setting :name, :required => true
+      add_setting :in, :required => true
+      add_setting :description, :default => ''
+      add_setting :required, :default => lambda { |parameter| parameter.in.to_s == 'path' ? true : false }
+      add_setting :schema
+      add_setting :type
+      add_setting :items
+      add_setting :default
+      add_setting :minimum
+      add_setting :maximum
+      add_setting :enum
+
+      def description_with_example
+        str = description_without_example.dup || ''
+        if with_example && value
+          str << "\n" unless str.empty?
+          str << "Eg, `#{value}`"
+        end
+        str
+      end
+
+      alias_method :description_without_example, :description
+      alias_method :description, :description_with_example
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/path.rb

@@ -0,0 +1,13 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Path < Node
+      add_setting :get, :schema => Operation
+      add_setting :put, :schema => Operation
+      add_setting :post, :schema => Operation
+      add_setting :delete, :schema => Operation
+      add_setting :options, :schema => Operation
+      add_setting :head, :schema => Operation
+      add_setting :patch, :schema => Operation
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/paths.rb

@@ -0,0 +1,7 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Paths < Node
+      CHILD_CLASS = Path
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/response.rb

@@ -0,0 +1,10 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Response < Node
+      add_setting :description, :required => true, :default => 'Successful operation'
+      add_setting :schema, :schema => Schema
+      add_setting :headers, :schema => Headers
+      add_setting :examples, :schema => Example
+    end
+  end
+end