rspec-api-docs 0.1.0 → 0.2.0

data/lib/rspec_api_docs/formatter/renderer/raddocs_renderer/index_serializer.rb

@@ -0,0 +1,57 @@
+require 'rspec_api_docs/formatter/renderer/raddocs_renderer/link'
+require 'rspec_api_docs/formatter/resource'
+
+module RspecApiDocs
+  module Renderer
+    class RaddocsRenderer
+      class IndexSerializer
+        class ExampleSerializer
+          attr_reader :example, :resource_name
+
+          def initialize(example, resource_name)
+            @example = example
+            @resource_name = resource_name
+          end
+
+          def to_h
+            {
+              description: example.name,
+              link: link,
+              groups: groups,
+              route: example.path,
+              method: example.http_method.downcase,
+            }
+          end
+
+          private
+
+          def link
+            Link.(resource_name, example.name)
+          end
+
+          def groups
+            'all'
+          end
+        end
+
+        attr_reader :resources
+
+        def initialize(resources)
+          @resources = resources
+        end
+
+        def to_h
+          {
+            resources: resources.map do |resource|
+              {
+                name: resource.name,
+                explanation: nil,
+                examples: resource.examples.map { |example| ExampleSerializer.new(example, resource.name).to_h },
+              }
+            end,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rspec_api_docs/formatter/renderer/raddocs_renderer/link.rb

@@ -0,0 +1,11 @@
+module RspecApiDocs
+  module Renderer
+    class RaddocsRenderer
+      class Link
+        def self.call(resource_name, example_name)
+          "#{resource_name.parameterize.underscore}/#{example_name.parameterize.underscore}.json"
+        end
+      end
+    end
+  end
+end

data/lib/rspec_api_docs/formatter/renderer/raddocs_renderer/resource_serializer.rb

@@ -0,0 +1,58 @@
+module RspecApiDocs
+  module Renderer
+    class RaddocsRenderer
+      class ResourceSerializer
+        attr_reader :resource, :example
+
+        def initialize(resource, example)
+          @resource = resource
+          @example = example
+        end
+
+        def to_h # rubocop:disable Metrics/AbcSize
+          {
+            resource: resource.name,
+            resource_explanation: nil,
+            http_method: example.http_method,
+            route: example.path,
+            description: example.name,
+            explanation: example.description,
+            parameters: parameters(example.parameters),
+            response_fields: response_fields(example.response_fields),
+            requests: requests,
+          }
+        end
+
+        private
+
+        def requests
+          example.requests.map { |request| request.merge(curl: nil) }
+        end
+
+        def parameters(parameters)
+          parameters.map do |parameter|
+            result = {}
+            result[:required] = true if parameter.required
+            result[:scope] = parameter.scope
+            result = result.merge(
+              name: parameter.name,
+              description: parameter.description,
+            )
+            result
+          end
+        end
+
+        def response_fields(fields)
+          fields.map do |field|
+            {
+              scope: field.scope,
+              Type: field.type,
+              name: field.name,
+              description: field.description,
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec_api_docs/formatter/renderer/slate_renderer.rb

@@ -0,0 +1,29 @@
+module RspecApiDocs
+  module Renderer
+    class SlateRenderer
+      attr_reader :resources
+
+      def initialize(resources)
+        @resources = resources
+      end
+
+      def render
+        FileUtils.mkdir_p output_file.dirname
+
+        File.open(output_file, 'w') do |f|
+          f.write ERB.new(File.read(template), nil, '-').result(binding)
+        end
+      end
+
+      private
+
+      def output_file
+        Pathname.new(RspecApiDocs.configuration.output_dir) + 'index.html.md'
+      end
+
+      def template
+        File.expand_path('../slate_renderer/slate_index.html.md.erb', __FILE__)
+      end
+    end
+  end
+end

data/lib/rspec_api_docs/formatter/renderer/slate_renderer/slate_index.html.md.erb

@@ -0,0 +1,45 @@
+---
+title: API Reference
+search: true
+---
+
+<% resources.each do |resource| %>
+# <%= resource.name %>
+
+<% resource.examples.each do |example| %>
+## <%= example.name %>
+
+<%= example.description %>
+
+<% example.requests.each do |request| -%>
+```json
+<% response_body = JSON.parse(request[:response_body]) if request[:response_body] %>
+<%= JSON.pretty_generate(response_body) if response_body %>
+```
+
+### HTTP Request
+
+`<%= request[:request_method] %> http://example.com<%= request[:request_path] %>`
+
+<% end -%>
+<% unless example.parameters.empty? -%>
+### Query Parameters
+
+Parameter | Required | Description
+--------- | ------- | -----------
+<% example.parameters.each do |parameter| -%>
+<%= parameter.name %> | <%= !!parameter.required %> | <%= parameter.description %>
+<% end -%>
+<% end -%>
+
+<% unless example.response_fields.empty? -%>
+### Response Fields
+
+Parameter | Type | Description
+--------- | ------- | -----------
+<% example.response_fields.each do |parameter| -%>
+<%= parameter.name %> | <%= parameter.type %> | <%= parameter.description %>
+<% end -%>
+<% end -%>
+<% end -%>
+<% end -%>

data/lib/rspec_api_docs/formatter/resource.rb

@@ -1,130 +1,44 @@
 require 'active_support/inflector'
+require 'rspec_api_docs/formatter/resource/example'
+require 'rspec_api_docs/formatter/resource/parameter'
+require 'rspec_api_docs/formatter/resource/response_field'
 
 module RspecApiDocs
   class Resource
-    attr_reader :example
+    attr_reader :rspec_example
 
-    def initialize(example)
-      @example = example
-    end
+    # Returns an array of {Example}s
+    #
+    # @return [Array<Example>]
+    attr_accessor :examples
 
-    def name
-      metadata.fetch(:resource_name, example.metadata[:example_group][:description])
+    def initialize(rspec_example)
+      @rspec_example = rspec_example
+      @examples = []
     end
 
-    def example_name
-      metadata.fetch(:example_name, example.description)
+    # The name of the resource.
+    #
+    # E.g. "Characters"
+    #
+    # @return [String]
+    def name
+      metadata.fetch(:resource_name, rspec_example.metadata[:example_group][:description])
     end
 
+    # The description of the resource.
+    #
+    # E.g. "Orders can be created, viewed, and deleted"
+    #
+    # @return [String]
     def description
-      metadata[:description]
-    end
-
-    def parameters
-      metadata.fetch(:parameters, []).map do |name, field|
-        result = {}
-        result[:required] = true if field[:required]
-        result[:scope] = field[:scope].join unless field[:scope].empty?
-        result = result.merge(
-          name: name,
-          description: field[:description],
-        )
-        result
-      end
-    end
-
-    def response_fields
-      metadata.fetch(:fields, []).map do |name, field|
-        {
-          scope: field[:scope].join,
-          Type: field[:type],
-          name: name,
-          description: field[:description],
-        }
-      end
-    end
-
-    def requests
-      reqs = metadata.fetch(:requests, []).reject { |x| x.any?(&:nil?) }
-      reqs.map do |request, response|
-        {
-          request_method: request.request_method,
-          request_path: request_path(request),
-          request_body: request_body(request.body),
-          request_headers: request_headers(request.env),
-          request_query_parameters: request.params,
-          request_content_type: request.content_type,
-          response_status: response.status,
-          response_status_text: response_status_text(response.status),
-          response_body: response_body(response.body),
-          response_headers: response.headers,
-          response_content_type: response.content_type,
-          curl: curl,
-        }
-      end
-    end
-
-    # NOTE: returns the first route requested
-    def path
-      metadata.fetch(:path) do
-        reqs = metadata.fetch(:requests, []).reject { |x| x.any?(&:nil?) }
-        return if reqs.empty?
-        reqs.first.first.path
-      end
-    end
-
-    # NOTE: returns the first HTTP method used
-    def http_method
-      reqs = metadata.fetch(:requests, []).reject { |x| x.any?(&:nil?) }
-      return if reqs.empty?
-      reqs.first.first.request_method
-    end
-
-    def link
-      "#{name.downcase}/#{example_name.parameterize.underscore}.json"
-    end
-
-    def groups
-      'all'
+      metadata[:resource_description]
     end
 
     private
 
-    # http://stackoverflow.com/a/33235714/826820
-    def request_headers(env)
-      Hash[
-        *env.select { |k,v| k.start_with? 'HTTP_' }
-          .collect { |k,v| [k.sub(/^HTTP_/, ''), v] }
-          .collect { |k,v| [k.split('_').collect(&:capitalize).join('-'), v] }
-          .sort.flatten
-      ]
-    end
-
-    def request_path(request)
-      URI(request.path).tap do |uri|
-        uri.query = request.query_string unless request.query_string.empty?
-      end.to_s
-    end
-
-    def request_body(body)
-      body = body.read
-      body.empty? ? nil : body
-    end
-
-    def response_body(body)
-      body.empty? ? nil : body
-    end
-
-    def response_status_text(status)
-      Rack::Utils::HTTP_STATUS_CODES[status]
-    end
-
-    # TODO
-    def curl
-    end
-
     def metadata
-      example.metadata[METADATA_NAMESPACE]
+      rspec_example.metadata[METADATA_NAMESPACE]
     end
   end
 end

data/lib/rspec_api_docs/formatter/resource/example.rb

@@ -0,0 +1,125 @@
+module RspecApiDocs
+  class Resource
+    class Example
+      attr_reader :example
+
+      def initialize(example)
+        @example = example
+      end
+
+      # The name of the example.
+      #
+      # E.g. "Returns a Character"
+      #
+      # @return [String]
+      def name
+        metadata.fetch(:example_name, example.description)
+      end
+
+      # The description of the example.
+      #
+      # E.g. "For getting information about a Character."
+      #
+      # @return [String]
+      def description
+        metadata[:description]
+      end
+
+      # Parameters for the example.
+      #
+      # @return [Array<Parameter>]
+      def parameters
+        metadata.fetch(:parameters, []).map do |name, parameter|
+          Parameter.new(name, parameter)
+        end
+      end
+
+      # Response fields for the example.
+      #
+      # @return [Array<ResponseField>]
+      def response_fields
+        metadata.fetch(:fields, []).map do |name, field|
+          ResponseField.new(name, field)
+        end
+      end
+
+      # Requests stored for the example.
+      #
+      # @return [Array<Hash>]
+      def requests # rubocop:disable Metrics/AbcSize
+        request_response_pairs.map do |request, response|
+          {
+            request_method: request.request_method,
+            request_path: request_path(request),
+            request_body: request_body(request.body),
+            request_headers: request_headers(request.env),
+            request_query_parameters: request.params,
+            request_content_type: request.content_type,
+            response_status: response.status,
+            response_status_text: response_status_text(response.status),
+            response_body: response_body(response.body),
+            response_headers: response.headers,
+            response_content_type: response.content_type,
+          }
+        end
+      end
+
+      # Path stored on the example OR the path of first route requested.
+      #
+      # @return [String, nil]
+      def path
+        metadata.fetch(:path) do
+          return if request_response_pairs.empty?
+          request_response_pairs.first.first.path
+        end
+      end
+
+      # The HTTP method of first route requested.
+      #
+      # @return [String, nil]
+      def http_method
+        return if request_response_pairs.empty?
+        request_response_pairs.first.first.request_method
+      end
+
+      private
+
+      def request_response_pairs
+        metadata.fetch(:requests, []).reject { |pair| pair.any?(&:nil?) }
+      end
+
+      # http://stackoverflow.com/a/33235714/826820
+      def request_headers(env)
+        Hash[
+          *env.select { |k,v| k.start_with? 'HTTP_' }
+            .collect { |k,v| [k.sub(/^HTTP_/, ''), v] }
+            .collect { |k,v| [k.split('_').collect(&:capitalize).join('-'), v] }
+            .sort.flatten
+        ]
+      end
+
+      def request_path(request)
+        URI(request.path).tap do |uri|
+          uri.query = request.query_string unless request.query_string.empty?
+        end.to_s
+      end
+
+      def request_body(body)
+        body = body.read
+        body.empty? ? nil : body
+      end
+
+      def response_body(body)
+        body.empty? ? nil : body
+      end
+
+      def response_status_text(status)
+        Rack::Utils::HTTP_STATUS_CODES[status]
+      end
+
+      def metadata
+        example.metadata[METADATA_NAMESPACE]
+      end
+    end
+  end
+end