rspec_api_documentation 4.9.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 16b47e6bedc1c86cc5e418233eca8b80d16b5628
-  data.tar.gz: e1da890616a2fa4cf6a8ff8c44eff5977abc32f6
+  metadata.gz: eab76d5c83c6d908b0d547852bf776001916a096
+  data.tar.gz: e104765306842544aae1e13e425df1048898490e
 SHA512:
-  metadata.gz: c16d4338f5d6e06f1c913a951c1370b31f2e6c85a6aef38a593d5fbd332226ad99c9fae76207e9bed5089500010a5b588a123e0354cdef25d057cbc0483a1933
-  data.tar.gz: 03ef3fbf5306d2951fa6f3b82f08e2679306069e791ef9bf5d30f58693dbb83528bb78009821cc4b26fb1da166c33620c1e5d327c9d91f8008bd45afa93eead4
+  metadata.gz: 950451c2559d9a185e3afd901ce7253c8c11d47dc2dff603e210b7d38fcb591cf0f15382113919f4c6bda2b4d90488a7c9c9fd7170ce39047c2091436694259c
+  data.tar.gz: 7f319b73f94430152e6a6d161fb63f61abfb7d2bffc73109298a7caea084325ee9deba64425880b1991a0c9d04ac025a8542448e252ff7a867947f0b68def133

data/lib/rspec_api_documentation.rb

@@ -44,6 +44,7 @@ module RspecApiDocumentation
     autoload :CombinedTextWriter
     autoload :CombinedJsonWriter
     autoload :SlateWriter
+    autoload :ApiBlueprintWriter
   end
 
   module Views
@@ -59,6 +60,8 @@ module RspecApiDocumentation
     autoload :MarkdownExample
     autoload :SlateIndex
     autoload :SlateExample
+    autoload :ApiBlueprintIndex
+    autoload :ApiBlueprintExample
   end
 
   def self.configuration

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/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

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
@@ -96,8 +98,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)

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
@@ -75,6 +95,10 @@ module RspecApiDocumentation::DSL
         safe_metadata(:parameters, [])
       end
 
+      def attributes
+        safe_metadata(:attributes, [])
+      end
+
       def response_fields
         safe_metadata(:response_fields, [])
       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/railtie.rb

@@ -1,7 +1,7 @@
 module RspecApiDocumentation
   class Railtie < Rails::Railtie
     rake_tasks do
-      load "tasks/docs.rake"
+      load File.join(File.dirname(__FILE__), '../tasks/docs.rake')
     end
   end
 end

data/lib/rspec_api_documentation/views/api_blueprint_example.rb

@@ -0,0 +1,104 @@
+module RspecApiDocumentation
+  module Views
+    class ApiBlueprintExample < MarkupExample
+      TOTAL_SPACES_INDENTATION = 8.freeze
+
+      def initialize(example, configuration)
+        super
+        self.template_name = "rspec_api_documentation/api_blueprint_example"
+      end
+
+      def parameters
+        super.map do |parameter|
+          parameter.merge({
+            :required => !!parameter[:required],
+            :has_example => !!parameter[:example],
+            :has_type => !!parameter[:type]
+          })
+        end
+      end
+
+      def requests
+        super.map do |request|
+          request[:request_headers_text]  = remove_utf8_for_json(request[:request_headers_text])
+          request[:request_headers_text]  = indent(request[:request_headers_text])
+          request[:request_content_type]  = content_type(request[:request_headers])
+          request[:request_content_type]  = remove_utf8_for_json(request[:request_content_type])
+          request[:request_body]          = body_to_json(request, :request)
+          request[:request_body]          = indent(request[:request_body])
+
+          request[:response_headers_text] = remove_utf8_for_json(request[:response_headers_text])
+          request[:response_headers_text] = indent(request[:response_headers_text])
+          request[:response_content_type] = content_type(request[:response_headers])
+          request[:response_content_type] = remove_utf8_for_json(request[:response_content_type])
+          request[:response_body]         = body_to_json(request, :response)
+          request[:response_body]         = indent(request[:response_body])
+
+          request[:has_request?]          = has_request?(request)
+          request[:has_response?]         = has_response?(request)
+          request
+        end
+      end
+
+      def extension
+        Writers::ApiBlueprintWriter::EXTENSION
+      end
+
+      private
+
+      def has_request?(metadata)
+        metadata.any? do |key, value|
+          [:request_body, :request_headers, :request_content_type].include?(key) && value
+        end
+      end
+
+      def has_response?(metadata)
+        metadata.any? do |key, value|
+          [:response_status, :response_body, :response_headers, :response_content_type].include?(key) && value
+        end
+      end
+
+      def indent(string)
+        string.tap do |str|
+          str.gsub!(/\n/, "\n" + (" " * TOTAL_SPACES_INDENTATION)) if str
+        end
+      end
+
+      # http_call: the hash that contains all information about the HTTP
+      #            request and response.
+      # message_direction: either `request` or `response`.
+      def body_to_json(http_call, message_direction)
+        content_type = http_call["#{message_direction}_content_type".to_sym]
+        body         = http_call["#{message_direction}_body".to_sym] # e.g request_body
+
+        if json?(content_type) && body
+          body = JSON.pretty_generate(JSON.parse(body))
+        end
+
+        body
+      end
+
+      # JSON requests should use UTF-8 by default according to
+      # http://www.ietf.org/rfc/rfc4627.txt, so we will remove `charset=utf-8`
+      # when we find it to remove noise.
+      def remove_utf8_for_json(headers)
+        return unless headers
+        headers
+          .split("\n")
+          .map { |header|
+            header.gsub!(/; *charset=utf-8/, "") if json?(header)
+            header
+          }
+          .join("\n")
+      end
+
+      def content_type(headers)
+        headers && headers.fetch("Content-Type", nil)
+      end
+
+      def json?(string)
+        string =~ /application\/.*json/
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/views/api_blueprint_index.rb

@@ -0,0 +1,90 @@
+module RspecApiDocumentation
+  module Views
+    class ApiBlueprintIndex < MarkupIndex
+      def initialize(index, configuration)
+        super
+        self.template_name = "rspec_api_documentation/api_blueprint_index"
+      end
+
+      def sections
+        super.map do |section|
+          routes = section[:examples].group_by { |e| "#{e.route_uri}#{e.route_optionals}" }.map do |route, examples|
+            attrs  = fields(:attributes, examples)
+            params = fields(:parameters, examples)
+
+            methods = examples.group_by(&:http_method).map do |http_method, examples|
+              {
+                http_method: http_method,
+                description: examples.first.respond_to?(:action_name) && examples.first.action_name,
+                examples: examples
+              }
+            end
+
+            {
+              "has_attributes?".to_sym => attrs.size > 0,
+              "has_parameters?".to_sym => params.size > 0,
+              route: route,
+              route_name: examples[0][:route_name],
+              attributes: attrs,
+              parameters: params,
+              http_methods: methods
+            }
+          end
+
+          section.merge({
+            routes: routes
+          })
+        end
+      end
+
+      def examples
+        @index.examples.map do |example|
+          ApiBlueprintExample.new(example, @configuration)
+        end
+      end
+
+      private
+
+      # APIB has both `parameters` and `attributes`. This generates a hash
+      # with all of its properties, like name, description, required.
+      #   {
+      #     required: true,
+      #     example: "1",
+      #     type: "string",
+      #     name: "id",
+      #     description: "The id",
+      #     properties_description: "required, string"
+      #   }
+      def fields(property_name, examples)
+        examples
+          .map { |example| example.metadata[property_name] }
+          .flatten
+          .compact
+          .uniq { |property| property[:name] }
+          .map do |property|
+            properties = []
+            properties << "required"      if property[:required]
+            properties << property[:type] if property[:type]
+            if properties.count > 0
+              property[:properties_description] = properties.join(", ")
+            else
+              property[:properties_description] = nil
+            end
+
+            property[:description] = nil if description_blank?(property)
+            property
+          end
+      end
+
+      # When no `description` was specified for a parameter, the DSL class
+      # is making `description = "#{scope} #{name}"`, which is bad because it
+      # assumes that all formats want this behavior. To avoid changing there
+      # and breaking everything, I do my own check here and if description
+      # equals the name, I assume it is blank.
+      def description_blank?(property)
+        !property[:description] ||
+          property[:description].to_s.strip == property[:name].to_s.strip
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/views/markup_example.rb

@@ -83,6 +83,10 @@ module RspecApiDocumentation
           end
         end.join
       end
+
+      def content_type(headers)
+        headers && headers.fetch("Content-Type", nil)
+      end
     end
   end
 end

data/lib/rspec_api_documentation/writers/api_blueprint_writer.rb

@@ -0,0 +1,29 @@
+module RspecApiDocumentation
+  module Writers
+    class ApiBlueprintWriter < GeneralMarkupWriter
+      EXTENSION = 'apib'
+
+      def markup_index_class
+        RspecApiDocumentation::Views::ApiBlueprintIndex
+      end
+
+      def markup_example_class
+        RspecApiDocumentation::Views::ApiBlueprintExample
+      end
+
+      def extension
+        EXTENSION
+      end
+
+      private
+
+      # API Blueprint is a spec, not navigable like HTML, therefore we generate
+      # only one file with all resources.
+      def render_options
+        super.merge({
+          examples: false
+        })
+      end
+    end
+  end
+end

data/lib/rspec_api_documentation/writers/general_markup_writer.rb

@@ -6,16 +6,20 @@ module RspecApiDocumentation
 
       # Write out the generated documentation
       def write
-        File.open(configuration.docs_dir.join(index_file_name + '.' + extension), "w+") do |f|
-          f.write markup_index_class.new(index, configuration).render
+        if render_options.fetch(:index, true)
+          File.open(configuration.docs_dir.join(index_file_name + '.' + extension), "w+") do |f|
+            f.write markup_index_class.new(index, configuration).render
+          end
         end
 
-        index.examples.each do |example|
-          markup_example = markup_example_class.new(example, configuration)
-          FileUtils.mkdir_p(configuration.docs_dir.join(markup_example.dirname))
+        if render_options.fetch(:examples, true)
+          index.examples.each do |example|
+            markup_example = markup_example_class.new(example, configuration)
+            FileUtils.mkdir_p(configuration.docs_dir.join(markup_example.dirname))
 
-          File.open(configuration.docs_dir.join(markup_example.dirname, markup_example.filename), "w+") do |f|
-            f.write markup_example.render
+            File.open(configuration.docs_dir.join(markup_example.dirname, markup_example.filename), "w+") do |f|
+              f.write markup_example.render
+            end
           end
         end
       end
@@ -27,6 +31,15 @@ module RspecApiDocumentation
       def extension
         raise 'Parent class. This method should not be called.'
       end
+
+      private
+
+      def render_options
+        {
+          index:    true,
+          examples: true
+        }
+      end
     end
   end
 end

data/templates/rspec_api_documentation/api_blueprint_index.mustache

@@ -0,0 +1,79 @@
+FORMAT: A1
+{{# sections }}
+
+# Group {{ resource_name }}
+{{# resource_explanation }}
+
+{{{ resource_explanation }}}
+{{/ resource_explanation }}
+{{# description }}
+
+{{ description }}
+{{/ description }}
+{{# routes }}
+
+## {{ route_name }} [{{ route }}]
+{{# description }}
+
+description: {{ description }}
+{{/ description }}
+{{# explanation }}
+
+explanation: {{ explanation }}
+{{/ explanation }}
+{{# has_parameters? }}
+
++ Parameters
+{{# parameters }}
+  + {{ name }}{{# example }}: {{ example }}{{/ example }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }}
+{{/ parameters }}
+{{/ has_parameters? }}
+{{# has_attributes? }}
+
++ Attributes (object)
+{{# attributes }}
+  + {{ name }}{{# example }}: {{ example }}{{/ example }}{{# properties_description }} ({{ properties_description }}){{/ properties_description }}{{# description }} - {{ description }}{{/ description }}
+{{/ attributes }}
+{{/ has_attributes? }}
+{{# http_methods }}
+
+### {{ description }} [{{ http_method }}]
+{{# examples }}
+{{# requests }}
+{{# has_request? }}
+
++ Request {{ description }}{{# request_content_type }} ({{ request_content_type }}){{/ request_content_type }}
+{{/ has_request? }}
+{{# request_headers_text }}
+
+    + Headers
+
+        {{{ request_headers_text }}}
+{{/ request_headers_text }}
+{{# request_body }}
+
+    + Body
+
+        {{{ request_body }}}
+{{/ request_body }}
+{{# has_response? }}
+
++ Response {{ response_status }} ({{ response_content_type }})
+{{/ has_response? }}
+{{# response_headers_text }}
+
+    + Headers
+
+        {{{ response_headers_text }}}
+{{/ response_headers_text }}
+{{# response_body }}
+
+    + Body
+
+        {{{ response_body }}}
+{{/ response_body }}
+{{/ requests }}
+{{/ examples }}
+{{/ http_methods }}
+{{/ routes }}
+{{/ sections }}

data/templates/rspec_api_documentation/markdown_example.mustache

@@ -25,10 +25,11 @@
 {{# has_response_fields? }}
 
 ### Response Fields
-{{# response_fields }}
 
-Name : {{ name }}
-Description : {{ description }}
+| Name | Description | Scope |
+|------|-------------|-------|
+{{# response_fields }}
+| {{ name }} | {{ description }} | {{ scope }} |
 {{/ response_fields }}
 
 {{/ has_response_fields? }}

data/templates/rspec_api_documentation/slate_example.mustache

@@ -9,7 +9,7 @@
 #### Endpoint
 
 {{# requests}}
-```
+```plaintext
 {{ request_method }} {{ request_path }}
 {{ request_headers_text }}
 ```
@@ -50,7 +50,7 @@ None known.
 
 ### Response
 
-```
+```plaintext
 {{ response_headers_text }}
 {{ response_status }} {{ response_status_text}}
 ```

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec_api_documentation
 version: !ruby/object:Gem::Version
-  version: 4.9.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Chris Cahoon
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-08 00:00:00.000000000 Z
+date: 2017-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -282,6 +282,8 @@ files:
 - lib/rspec_api_documentation/rack_test_client.rb
 - lib/rspec_api_documentation/railtie.rb
 - lib/rspec_api_documentation/test_server.rb
+- lib/rspec_api_documentation/views/api_blueprint_example.rb
+- lib/rspec_api_documentation/views/api_blueprint_index.rb
 - lib/rspec_api_documentation/views/html_example.rb
 - lib/rspec_api_documentation/views/html_index.rb
 - lib/rspec_api_documentation/views/markdown_example.rb
@@ -292,6 +294,7 @@ files:
 - lib/rspec_api_documentation/views/slate_index.rb
 - lib/rspec_api_documentation/views/textile_example.rb
 - lib/rspec_api_documentation/views/textile_index.rb
+- lib/rspec_api_documentation/writers/api_blueprint_writer.rb
 - lib/rspec_api_documentation/writers/append_json_writer.rb
 - lib/rspec_api_documentation/writers/combined_json_writer.rb
 - lib/rspec_api_documentation/writers/combined_text_writer.rb
@@ -306,6 +309,7 @@ files:
 - lib/rspec_api_documentation/writers/textile_writer.rb
 - lib/rspec_api_documentation/writers/writer.rb
 - lib/tasks/docs.rake
+- templates/rspec_api_documentation/api_blueprint_index.mustache
 - templates/rspec_api_documentation/html_example.mustache
 - templates/rspec_api_documentation/html_index.mustache
 - templates/rspec_api_documentation/markdown_example.mustache