rspec_api_documentation 4.9.0 → 6.1.0

data/lib/rspec_api_documentation/open_api/responses.rb

@@ -0,0 +1,9 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Responses < Node
+      CHILD_CLASS = Response
+
+      add_setting :default, :default => lambda { |responses| responses.existing_settings.size > 1 ? nil : Response.new }
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/root.rb

@@ -0,0 +1,21 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Root < Node
+      add_setting :swagger, :default => '2.0', :required => true
+      add_setting :info, :default => Info.new, :required => true, :schema => Info
+      add_setting :host, :default => 'localhost:3000'
+      add_setting :basePath
+      add_setting :schemes, :default => %w(http https)
+      add_setting :consumes, :default => %w(application/json application/xml)
+      add_setting :produces, :default => %w(application/json application/xml)
+      add_setting :paths, :default => Paths.new, :required => true, :schema => Paths
+      add_setting :definitions
+      add_setting :parameters
+      add_setting :responses
+      add_setting :securityDefinitions, :schema => SecurityDefinitions
+      add_setting :security
+      add_setting :tags, :default => [], :schema => [Tag]
+      add_setting :externalDocs
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/schema.rb

@@ -0,0 +1,15 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Schema < Node
+      add_setting :format
+      add_setting :title
+      add_setting :description, :default => ''
+      add_setting :required
+      add_setting :enum
+      add_setting :type
+      add_setting :items
+      add_setting :properties
+      add_setting :example
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/security_definitions.rb

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

data/lib/rspec_api_documentation/open_api/security_schema.rb

@@ -0,0 +1,14 @@
+module RspecApiDocumentation
+  module OpenApi
+    class SecuritySchema < Node
+      add_setting :type, :required => true
+      add_setting :description, :default => ''
+      add_setting :name
+      add_setting :in
+      add_setting :flow
+      add_setting :authorizationUrl
+      add_setting :tokenUrl
+      add_setting :scopes
+    end
+  end
+end

data/lib/rspec_api_documentation/open_api/tag.rb

@@ -0,0 +1,9 @@
+module RspecApiDocumentation
+  module OpenApi
+    class Tag < Node
+      add_setting :name, :required => true
+      add_setting :description, :default => ''
+      add_setting :externalDocs
+    end
+  end
+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,116 @@
+module RspecApiDocumentation
+  module Views
+    class ApiBlueprintExample < MarkupExample
+      TOTAL_SPACES_INDENTATION = 12.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(remove_content_type(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(remove_content_type(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
+
+      # `Content-Type` header is removed because the information would be duplicated
+      # since it's already present in `request[:request_content_type]`.
+      def remove_content_type(headers)
+        return unless headers
+        headers
+          .split("\n")
+          .reject { |header|
+            header.start_with?('Content-Type:')
+          }
+          .join("\n")
+      end
+
+      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,105 @@
+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}#{e.route_name}" }.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: format_route(examples[0]),
+              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 follows the RFC 6570 to format URI templates.
+      # According to it, simple string expansion (used to perform variable
+      # expansion) should be represented by `{var}` and not by `/:var`
+      # For example `/posts/:id` should become `/posts/{id}`
+      # cf. https://github.com/apiaryio/api-blueprint/blob/format-1A/API%20Blueprint%20Specification.md#431-resource-section
+      # cf. https://tools.ietf.org/html/rfc6570#section-3.2.6
+      def format_route(example)
+        route_uri = example[:route_uri].gsub(/:(.*?)([.\/?{]|$)/, '{\1}\2')
+        "#{route_uri}#{example[:route_optionals]}"
+      end
+
+      # 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 = []
+            if property[:required] == true
+              properties << 'required'
+            else
+              properties << 'optional'
+            end
+            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/markdown_example.rb

@@ -1,7 +1,7 @@
 module RspecApiDocumentation
   module Views
     class MarkdownExample < MarkupExample
-      EXTENSION = 'markdown'
+      EXTENSION = 'md'
 
       def initialize(example, configuration)
         super

data/lib/rspec_api_documentation/views/markup_example.rb

@@ -3,6 +3,8 @@ require 'mustache'
 module RspecApiDocumentation
   module Views
     class MarkupExample < Mustache
+      SPECIAL_CHARS = /[<>:"\/\\|?*]/.freeze
+
       def initialize(example, configuration)
         @example = example
         @host = configuration.curl_host
@@ -19,12 +21,11 @@ module RspecApiDocumentation
       end
 
       def dirname
-        resource_name.to_s.downcase.gsub(/\s+/, '_').gsub(":", "_")
+        sanitize(resource_name.to_s.downcase)
       end
 
       def filename
-        special_chars = /[<>:"\/\\|?*]/
-        basename = description.downcase.gsub(/\s+/, '_').gsub(special_chars, '')
+        basename = sanitize(description.downcase)
         basename = Digest::MD5.new.update(description).to_s if basename.blank?
         "#{basename}.#{extension}"
       end
@@ -83,6 +84,14 @@ module RspecApiDocumentation
           end
         end.join
       end
+
+      def content_type(headers)
+        headers && headers.fetch("Content-Type", nil)
+      end
+
+      def sanitize(name)
+        name.gsub(/\s+/, '_').gsub(SPECIAL_CHARS, '')
+      end
     end
   end
 end

data/lib/rspec_api_documentation/views/markup_index.rb

@@ -3,16 +3,14 @@ require 'mustache'
 module RspecApiDocumentation
   module Views
     class MarkupIndex < Mustache
+      delegate :api_name, :api_explanation, to: :@configuration, prefix: false
+
       def initialize(index, configuration)
         @index = index
         @configuration = configuration
         self.template_path = configuration.template_path
       end
 
-      def api_name
-        @configuration.api_name
-      end
-
       def sections
         RspecApiDocumentation::Writers::IndexHelper.sections(examples, @configuration)
       end

data/lib/rspec_api_documentation/views/slate_index.rb

@@ -1,6 +1,10 @@
 module RspecApiDocumentation
   module Views
     class SlateIndex < MarkdownIndex
+      def initialize(index, configuration)
+        super
+        self.template_name = "rspec_api_documentation/slate_index"
+      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/combined_json_writer.rb

@@ -7,7 +7,7 @@ module RspecApiDocumentation
         File.open(configuration.docs_dir.join("combined.json"), "w+") do |f|
           examples = []
           index.examples.each do |rspec_example|
-            examples << Formatter.to_json(JsonExample.new(rspec_example, configuration))
+            examples << Formatter.to_json(JSONExample.new(rspec_example, configuration))
           end
 
           f.write "["

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/lib/rspec_api_documentation/writers/json_iodocs_writer.rb

@@ -32,7 +32,7 @@ module RspecApiDocumentation
       end
 
       def examples
-        @index.examples.map { |example| JsonExample.new(example, @configuration) }
+        @index.examples.map { |example| JsonIodocsExample.new(example, @configuration) }
       end
 
       def as_json(opts = nil)
@@ -48,7 +48,7 @@ module RspecApiDocumentation
       end
     end
 
-    class JsonExample
+    class JsonIodocsExample
       def initialize(example, configuration)
         @example = example
       end
@@ -94,6 +94,7 @@ module RspecApiDocumentation
         {
           @api_key.to_sym => {
             :name => @configuration.api_name,
+            :description => @configuration.api_explanation,
             :protocol => @configuration.io_docs_protocol,
             :publicPath => "",
             :baseURL => @configuration.curl_host

data/lib/rspec_api_documentation/writers/json_writer.rb

@@ -2,19 +2,19 @@ require 'rspec_api_documentation/writers/formatter'
 
 module RspecApiDocumentation
   module Writers
-    class JsonWriter < Writer
+    class JSONWriter < Writer
       delegate :docs_dir, :to => :configuration
 
       def write
         File.open(docs_dir.join("index.json"), "w+") do |f|
-          f.write Formatter.to_json(JsonIndex.new(index, configuration))
+          f.write Formatter.to_json(JSONIndex.new(index, configuration))
         end
         write_examples
       end
 
       def write_examples
         index.examples.each do |example|
-          json_example = JsonExample.new(example, configuration)
+          json_example = JSONExample.new(example, configuration)
           FileUtils.mkdir_p(docs_dir.join(json_example.dirname))
           File.open(docs_dir.join(json_example.dirname, json_example.filename), "w+") do |f|
             f.write Formatter.to_json(json_example)
@@ -23,7 +23,11 @@ module RspecApiDocumentation
       end
     end
 
-    class JsonIndex
+    # https://github.com/zipmark/rspec_api_documentation/issues/382
+    # backward compatibilty json for configuration of config.format
+    class JsonWriter < JSONWriter; end
+
+    class JSONIndex
       def initialize(index, configuration)
         @index = index
         @configuration = configuration
@@ -34,7 +38,7 @@ module RspecApiDocumentation
       end
 
       def examples
-        @index.examples.map { |example| JsonExample.new(example, @configuration) }
+        @index.examples.map { |example| JSONExample.new(example, @configuration) }
       end
 
       def as_json(opts = nil)
@@ -61,7 +65,7 @@ module RspecApiDocumentation
       end
     end
 
-    class JsonExample
+    class JSONExample
       def initialize(example, configuration)
         @example = example
         @host = configuration.curl_host

data/lib/rspec_api_documentation/writers/markdown_writer.rb

@@ -1,7 +1,7 @@
 module RspecApiDocumentation
   module Writers
     class MarkdownWriter < GeneralMarkupWriter
-      EXTENSION = 'markdown'
+      EXTENSION = 'md'
 
       def markup_index_class
         RspecApiDocumentation::Views::MarkdownIndex