rspec_api_documentation 4.9.0 → 6.1.0

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

data/lib/rspec_api_documentation/writers/slate_writer.rb

@@ -21,17 +21,11 @@ module RspecApiDocumentation
       def write
         File.open(configuration.docs_dir.join("#{FILENAME}.#{extension}"), 'w+') do |file|
 
-          file.write %Q{---\n}
-          file.write %Q{title: "#{configuration.api_name}"\n}
-          file.write %Q{language_tabs:\n}
-          file.write %Q{  - json: JSON\n}
-          file.write %Q{  - shell: cURL\n}
-          file.write %Q{---\n\n}
+          file.write markup_index_class.new(index, configuration).render
 
           IndexHelper.sections(index.examples, @configuration).each do |section|
-
             file.write "# #{section[:resource_name]}\n\n"
-            section[:examples].sort_by!(&:description) unless configuration.keep_source_order
+            file.write "#{section[:resource_explanation]}\n\n"
 
             section[:examples].each do |example|
               markup_example = markup_example_class.new(example, configuration)

data/lib/rspec_api_documentation.rb

@@ -37,6 +37,7 @@ module RspecApiDocumentation
     autoload :HtmlWriter
     autoload :TextileWriter
     autoload :MarkdownWriter
+    autoload :JSONWriter
     autoload :JsonWriter
     autoload :AppendJsonWriter
     autoload :JsonIodocsWriter
@@ -44,6 +45,32 @@ module RspecApiDocumentation
     autoload :CombinedTextWriter
     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
@@ -59,6 +86,8 @@ module RspecApiDocumentation
     autoload :MarkdownExample
     autoload :SlateIndex
     autoload :SlateExample
+    autoload :ApiBlueprintIndex
+    autoload :ApiBlueprintExample
   end
 
   def self.configuration

data/templates/rspec_api_documentation/api_blueprint_index.mustache

@@ -0,0 +1,80 @@
+FORMAT: 1A
+# {{ api_name }}
+{{# 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/html_index.mustache

@@ -10,7 +10,7 @@
 <body>
 <div class="container">
   <h1>{{ api_name }}</h1>
-
+  {{{ api_explanation }}}
   {{# sections }}
   <div class="article">
     <h2>{{ resource_name }}</h2>

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/markdown_index.mustache

@@ -1,4 +1,5 @@
 # {{ api_name }}
+{{{ api_explanation }}}
 
 {{# sections }}
 ## {{ resource_name }}

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}}
 ```

data/templates/rspec_api_documentation/slate_index.mustache

@@ -0,0 +1,8 @@
+---
+title: {{ api_name }}
+language_tabs:
+  - json: JSON
+  - shell: cURL
+---
+
+{{{ api_explanation }}}

data/templates/rspec_api_documentation/textile_index.mustache

@@ -1,4 +1,5 @@
 h1. {{ api_name }}
+{{{ api_explanation }}}
 
 {{# sections }}
 h2. {{ resource_name }}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec_api_documentation
 version: !ruby/object:Gem::Version
-  version: 4.9.0
+  version: 6.1.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: 2018-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -252,6 +252,40 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.6.3
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.8.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.8.2
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.11
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.11
 description: Generate API docs from your test suite
 email:
 - chris@smartlogicsolutions.com
@@ -279,9 +313,30 @@ files:
 - lib/rspec_api_documentation/http_test_client.rb
 - lib/rspec_api_documentation/index.rb
 - lib/rspec_api_documentation/oauth2_mac_client.rb
+- lib/rspec_api_documentation/open_api/contact.rb
+- lib/rspec_api_documentation/open_api/example.rb
+- lib/rspec_api_documentation/open_api/header.rb
+- lib/rspec_api_documentation/open_api/headers.rb
+- lib/rspec_api_documentation/open_api/helper.rb
+- lib/rspec_api_documentation/open_api/info.rb
+- lib/rspec_api_documentation/open_api/license.rb
+- lib/rspec_api_documentation/open_api/node.rb
+- lib/rspec_api_documentation/open_api/operation.rb
+- lib/rspec_api_documentation/open_api/parameter.rb
+- lib/rspec_api_documentation/open_api/path.rb
+- lib/rspec_api_documentation/open_api/paths.rb
+- lib/rspec_api_documentation/open_api/response.rb
+- lib/rspec_api_documentation/open_api/responses.rb
+- lib/rspec_api_documentation/open_api/root.rb
+- lib/rspec_api_documentation/open_api/schema.rb
+- lib/rspec_api_documentation/open_api/security_definitions.rb
+- lib/rspec_api_documentation/open_api/security_schema.rb
+- lib/rspec_api_documentation/open_api/tag.rb
 - 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 +347,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
@@ -302,15 +358,18 @@ files:
 - lib/rspec_api_documentation/writers/json_iodocs_writer.rb
 - lib/rspec_api_documentation/writers/json_writer.rb
 - lib/rspec_api_documentation/writers/markdown_writer.rb
+- lib/rspec_api_documentation/writers/open_api_writer.rb
 - lib/rspec_api_documentation/writers/slate_writer.rb
 - 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
 - templates/rspec_api_documentation/markdown_index.mustache
 - templates/rspec_api_documentation/slate_example.mustache
+- templates/rspec_api_documentation/slate_index.mustache
 - templates/rspec_api_documentation/textile_example.mustache
 - templates/rspec_api_documentation/textile_index.mustache
 homepage: http://smartlogicsolutions.com
@@ -338,4 +397,3 @@ signing_key:
 specification_version: 4
 summary: A double black belt for your docs
 test_files: []
-has_rdoc: