rspec_api_documentation 5.1.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b64de927068173bdb8b5090658a90cfdfdebd87
-  data.tar.gz: 7d671588a963248bb37ca1b86d2ccb6139c5e4d0
+  metadata.gz: debdb41655fc2b0d61d43a0feaffa6a3c4e1ae6c
+  data.tar.gz: e560cee22b88bda2b3779a4e9f26561e3d4195ba
 SHA512:
-  metadata.gz: 45149d40631eb2c476fa099fb728da825ef831adbbe2032ae2ca07aa4b659e0950b6ac83c59568f83845c6328266a4a697ac8165308a385b2955c3a655143889
-  data.tar.gz: 06d59a0dd3153544799cdaa3803894f2e0210d97ff72e17812194a0b565ee5bc1b369e23ae6a66f93a8b03f54d0224024aa2adfa72d3ff774a084f5589ce795b
+  metadata.gz: 6530d774c6e77fe56a65ee073d74f7b7acec77d8feeb63aace0b0b931975f59253be12d8c091c6bae743b884db9cadf723159f59c273c0dfe2acfdb2eb0106a3
+  data.tar.gz: 08e6146400b65497daea2d47c257ecead4436a37779b689215bab75830aab20f66e9e71698cb14a02101aea334555aae8be69aad56736e69ba483581b150aea3

data/lib/rspec_api_documentation.rb

@@ -37,7 +37,7 @@ module RspecApiDocumentation
     autoload :HtmlWriter
     autoload :TextileWriter
     autoload :MarkdownWriter
-    autoload :JsonWriter
+    autoload :JSONWriter
     autoload :AppendJsonWriter
     autoload :JsonIodocsWriter
     autoload :IndexHelper
@@ -45,6 +45,31 @@ module RspecApiDocumentation
     autoload :CombinedJsonWriter
     autoload :SlateWriter
     autoload :ApiBlueprintWriter
+    autoload :OpenApiWriter
+  end
+
+  module OpenApi
+    extend ActiveSupport::Autoload
+
+    autoload :Helper
+    autoload :Node
+    autoload :Root
+    autoload :Info
+    autoload :Contact
+    autoload :License
+    autoload :Paths
+    autoload :Path
+    autoload :Tag
+    autoload :Operation
+    autoload :Parameter
+    autoload :Responses
+    autoload :Response
+    autoload :Example
+    autoload :Headers
+    autoload :Header
+    autoload :Schema
+    autoload :SecurityDefinitions
+    autoload :SecuritySchema
   end
 
   module Views

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/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")
@@ -110,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
@@ -119,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/dsl/endpoint.rb

@@ -38,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
@@ -74,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)|
@@ -144,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/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
@@ -51,11 +59,14 @@ module RspecApiDocumentation
             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/resource.rb

@@ -70,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
@@ -107,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/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