rspec_api_documentation 5.1.0 → 6.0.0

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

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/views/api_blueprint_example.rb

@@ -1,7 +1,7 @@
 module RspecApiDocumentation
   module Views
     class ApiBlueprintExample < MarkupExample
-      TOTAL_SPACES_INDENTATION = 8.freeze
+      TOTAL_SPACES_INDENTATION = 12.freeze
 
       def initialize(example, configuration)
         super
@@ -20,14 +20,14 @@ module RspecApiDocumentation
 
       def requests
         super.map do |request|
-          request[:request_headers_text]  = remove_utf8_for_json(request[:request_headers_text])
+          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(request[:response_headers_text])
+          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])
@@ -46,6 +46,18 @@ module RspecApiDocumentation
 
       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

data/lib/rspec_api_documentation/views/api_blueprint_index.rb

@@ -23,7 +23,7 @@ module RspecApiDocumentation
             {
               "has_attributes?".to_sym => attrs.size > 0,
               "has_parameters?".to_sym => params.size > 0,
-              route: route,
+              route: format_route(examples[0]),
               route_name: examples[0][:route_name],
               attributes: attrs,
               parameters: params,
@@ -45,6 +45,17 @@ module RspecApiDocumentation
 
       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.
       #   {
@@ -63,7 +74,11 @@ module RspecApiDocumentation
           .uniq { |property| property[:name] }
           .map do |property|
             properties = []
-            properties << "required"      if property[:required]
+            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(", ")

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
@@ -87,6 +88,10 @@ module RspecApiDocumentation
       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/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/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/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

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,7 @@ module RspecApiDocumentation
       end
     end
 
-    class JsonIndex
+    class JSONIndex
       def initialize(index, configuration)
         @index = index
         @configuration = configuration
@@ -34,7 +34,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 +61,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

data/lib/rspec_api_documentation/writers/open_api_writer.rb

@@ -0,0 +1,244 @@
+require 'rspec_api_documentation/writers/formatter'
+require 'yaml'
+
+module RspecApiDocumentation
+  module Writers
+    class OpenApiWriter < Writer
+      FILENAME = 'open_api'
+
+      delegate :docs_dir, :configurations_dir, to: :configuration
+
+      def write
+        File.open(docs_dir.join("#{FILENAME}.json"), 'w+') do |f|
+          f.write Formatter.to_json(OpenApiIndex.new(index, configuration, load_config))
+        end
+      end
+
+      private
+
+      def load_config
+        return JSON.parse(File.read("#{configurations_dir}/open_api.json")) if File.exist?("#{configurations_dir}/open_api.json")
+        YAML.load_file("#{configurations_dir}/open_api.yml") if File.exist?("#{configurations_dir}/open_api.yml")
+      end
+    end
+
+    class OpenApiIndex
+      attr_reader :index, :configuration, :init_config
+
+      def initialize(index, configuration, init_config)
+        @index = index
+        @configuration = configuration
+        @init_config = init_config
+      end
+
+      def as_json
+        @specs = OpenApi::Root.new(init_config)
+        add_tags!
+        add_paths!
+        add_security_definitions!
+        specs.as_json
+      end
+
+      private
+
+      attr_reader :specs
+
+      def examples
+        index.examples.map { |example| OpenApiExample.new(example) }
+      end
+
+      def add_security_definitions!
+        security_definitions = OpenApi::SecurityDefinitions.new
+
+        arr = examples.map do |example|
+          example.respond_to?(:authentications) ? example.authentications : nil
+        end.compact
+
+        arr.each do |securities|
+          securities.each do |security, opts|
+            schema = OpenApi::SecuritySchema.new(
+              name: opts[:name],
+              description: opts[:description],
+              type: opts[:type],
+              in: opts[:in]
+            )
+            security_definitions.add_setting security, :value => schema
+          end
+        end
+        specs.securityDefinitions = security_definitions unless arr.empty?
+      end
+
+      def add_tags!
+        tags = {}
+        examples.each do |example|
+          tags[example.resource_name] ||= example.resource_explanation
+        end
+        specs.safe_assign_setting(:tags, [])
+        tags.each do |name, desc|
+          specs.tags << OpenApi::Tag.new(name: name, description: desc) unless specs.tags.any? { |tag| tag.name == name }
+        end
+      end
+
+      def add_paths!
+        specs.safe_assign_setting(:paths, OpenApi::Paths.new)
+        examples.each do |example|
+          specs.paths.add_setting example.route, :value => OpenApi::Path.new
+
+          operation = specs.paths.setting(example.route).setting(example.http_method) || OpenApi::Operation.new
+
+          operation.safe_assign_setting(:tags, [example.resource_name])
+          operation.safe_assign_setting(:summary, example.respond_to?(:route_summary) ? example.route_summary : '')
+          operation.safe_assign_setting(:description, example.respond_to?(:route_description) ? example.route_description : '')
+          operation.safe_assign_setting(:responses, OpenApi::Responses.new)
+          operation.safe_assign_setting(:parameters, extract_parameters(example))
+          operation.safe_assign_setting(:consumes, example.requests.map { |request| request[:request_content_type] }.compact.map { |q| q[/[^;]+/] })
+          operation.safe_assign_setting(:produces, example.requests.map { |request| request[:response_content_type] }.compact.map { |q| q[/[^;]+/] })
+          operation.safe_assign_setting(:security, example.respond_to?(:authentications) ? example.authentications.map { |(k, _)| {k => []} } : [])
+
+          process_responses(operation.responses, example)
+
+          specs.paths.setting(example.route).assign_setting(example.http_method, operation)
+        end
+      end
+
+      def process_responses(responses, example)
+        schema = extract_schema(example.respond_to?(:response_fields) ? example.response_fields : [])
+        example.requests.each do |request|
+          response = OpenApi::Response.new(
+            description: example.description,
+            schema: schema
+          )
+
+          if request[:response_headers]
+            response.safe_assign_setting(:headers, OpenApi::Headers.new)
+            request[:response_headers].each do |header, value|
+              response.headers.add_setting header, :value => OpenApi::Header.new('x-example-value' => value)
+            end
+          end
+
+          if /\A(?<response_content_type>[^;]+)/ =~ request[:response_content_type]
+            response.safe_assign_setting(:examples, OpenApi::Example.new)
+            response_body = JSON.parse(request[:response_body]) rescue nil
+            response.examples.add_setting response_content_type, :value => response_body
+          end
+          responses.add_setting "#{request[:response_status]}", :value => response
+        end
+      end
+
+      def extract_schema(fields)
+        schema = {type: 'object', properties: {}}
+
+        fields.each do |field|
+          current = schema
+          if field[:scope]
+            [*field[:scope]].each do |scope|
+              current[:properties][scope] ||= {type: 'object', properties: {}}
+              current = current[:properties][scope]
+            end
+          end
+          current[:properties][field[:name]] = {type: field[:type] || OpenApi::Helper.extract_type(field[:value])}
+          current[:properties][field[:name]][:example] = field[:value] if field[:value] && field[:with_example]
+          current[:properties][field[:name]][:default] = field[:default] if field[:default]
+          current[:properties][field[:name]][:description] = field[:description] if field[:description]
+
+          opts = {enum: field[:enum], minimum: field[:minimum], maximum: field[:maximum]}
+
+          if current[:properties][field[:name]][:type] == :array
+            current[:properties][field[:name]][:items] = field[:items] || OpenApi::Helper.extract_items(field[:value][0], opts)
+          else
+            opts.each { |k, v| current[:properties][field[:name]][k] = v if v }
+          end
+
+          current[:required] ||= [] << field[:name] if field[:required]
+        end
+
+        OpenApi::Schema.new(schema)
+      end
+
+      def extract_parameters(example)
+        extract_known_parameters(example.extended_parameters.select { |p| !p[:in].nil? }) +
+          extract_unknown_parameters(example, example.extended_parameters.select { |p| p[:in].nil? })
+      end
+
+      def extract_parameter(opts)
+        OpenApi::Parameter.new(
+          name:         opts[:name],
+          in:           opts[:in],
+          description:  opts[:description],
+          required:     opts[:required],
+          type:         opts[:type] || OpenApi::Helper.extract_type(opts[:value]),
+          value:        opts[:value],
+          with_example: opts[:with_example],
+          default:      opts[:default],
+        ).tap do |elem|
+          if elem.type == :array
+            elem.items = opts[:items] || OpenApi::Helper.extract_items(opts[:value][0], { minimum: opts[:minimum], maximum: opts[:maximum], enum: opts[:enum] })
+          else
+            elem.minimum = opts[:minimum]
+            elem.maximum = opts[:maximum]
+            elem.enum    = opts[:enum]
+          end
+        end
+      end
+
+      def extract_unknown_parameters(example, parameters)
+        if example.http_method == :get
+          parameters.map { |parameter| extract_parameter(parameter.merge(in: :query)) }
+        elsif parameters.any? { |parameter| !parameter[:scope].nil? }
+          [OpenApi::Parameter.new(
+            name:        :body,
+            in:          :body,
+            description: '',
+            schema:      extract_schema(parameters)
+          )]
+        else
+          parameters.map { |parameter| extract_parameter(parameter.merge(in: :formData)) }
+        end
+      end
+
+      def extract_known_parameters(parameters)
+        result = parameters.select { |parameter| %w(query path header formData).include?(parameter[:in].to_s) }
+                   .map { |parameter| extract_parameter(parameter) }
+
+        body = parameters.select { |parameter| %w(body).include?(parameter[:in].to_s) }
+
+        result.unshift(
+          OpenApi::Parameter.new(
+            name: :body,
+            in: :body,
+            description: '',
+            schema: extract_schema(body)
+          )
+        ) unless body.empty?
+
+        result
+      end
+    end
+
+    class OpenApiExample
+      def initialize(example)
+        @example = example
+      end
+
+      def method_missing(method, *args, &block)
+        @example.send(method, *args, &block)
+      end
+
+      def respond_to?(method, include_private = false)
+        super || @example.respond_to?(method, include_private)
+      end
+
+      def http_method
+        metadata[:method]
+      end
+
+      def requests
+        super.select { |request| request[:request_method].to_s.downcase == http_method.to_s.downcase }
+      end
+
+      def route
+        super.gsub(/:(?<parameter>[^\/]+)/, '{\k<parameter>}')
+      end
+    end
+  end
+end