rspec-api-docs 0.1.0 → 0.2.0

data/lib/rspec_api_docs/config.rb

@@ -0,0 +1,27 @@
+module RspecApiDocs
+  class << self
+    attr_accessor :configuration
+
+    def configuration
+      @configuration ||= Config.new
+    end
+  end
+
+  def self.configure
+    self.configuration ||= Config.new
+    yield configuration
+  end
+
+  class Config
+    attr_accessor \
+      :output_dir,
+      :renderer,
+      :validate_params
+
+    def initialize
+      @output_dir = 'docs'
+      @renderer = :json
+      @validate_params = true
+    end
+  end
+end

data/lib/rspec_api_docs/dsl.rb

@@ -3,19 +3,44 @@ require 'rspec_api_docs/dsl/request_store'
 require 'rspec_api_docs/dsl/doc_proxy'
 
 module RspecApiDocs
+  # This module is intended to be included in your RSpec specs to expose the
+  # {#doc} method.
   module Dsl
-    def doc(&block)
-      example.metadata[METADATA_NAMESPACE] ||= {}
+    # DSL method for use in your RSpec examples.
+    #
+    # Usage:
+    #
+    #     it 'returns a character' do
+    #       doc do
+    #         title 'Returns a Character'
+    #         description 'Allows you to return a single character.'
+    #         path '/characters/:id'
+    #
+    #         param :id, 'The id of a character', required: true
+    #
+    #         field :id, 'The id of a character', scope: :character
+    #         field :name, "The character's name", scope: :character
+    #       end
+    #
+    #       get '/characters/1'
+    #     end
+    #
+    # For more info on the methods available in the block, see {DocProxy}.
+    #
+    # @param should_document [true, false] clear documentation metadata for the example
+    # @return [RequestStore, nil] an object to store request/response pairs
+    def doc(should_document = true, &block)
+      if should_document
+        example.metadata[METADATA_NAMESPACE] ||= {}
 
-      if block
-        DocProxy.new(example).instance_eval(&block)
-      end
-
-      RequestStore.new(example)
-    end
+        if block
+          DocProxy.new(example).instance_eval(&block)
+        end
 
-    def no_doc
-      example.metadata[METADATA_NAMESPACE] = nil
+        RequestStore.new(example)
+      else
+        example.metadata[METADATA_NAMESPACE] = nil
+      end
     end
 
     private

data/lib/rspec_api_docs/dsl/doc_proxy.rb

@@ -7,22 +7,74 @@ module RspecApiDocs
         @metadata = example.metadata
       end
 
+      # For setting the name of the example.
+      #
+      # E.g. "Returns a Character"
+      #
+      # @return [void]
       def name(value)
         metadata[METADATA_NAMESPACE][:example_name] = value
       end
 
+      # For setting the name of the resource.
+      #
+      # E.g. "Characters"
+      #
+      # @return [void]
       def resource_name(value)
         metadata[METADATA_NAMESPACE][:resource_name] = value
       end
 
+      # For setting the description of the resource.
+      #
+      # E.g. "Orders can be created, viewed, and deleted"
+      #
+      # @return [void]
+      def resource_description(value)
+        metadata[METADATA_NAMESPACE][:resource_description] = value
+      end
+
+      # For setting a description of the example.
+      #
+      # E.g. "Allows you to return a single character."
+      #
+      # @return [void]
       def description(value)
         metadata[METADATA_NAMESPACE][:description] = value
       end
 
+      # For setting the request path of the example.
+      #
+      # E.g. "/characters/:id"
+      #
+      # @return [void]
       def path(value)
         metadata[METADATA_NAMESPACE][:path] = value
       end
 
+      # For setting response fields of a request.
+      #
+      # Usage:
+      #
+      #     doc do
+      #       field :id, 'The id of a character', scope: :character
+      #       field :name, "The character's name", scope: :character
+      #     end
+      #
+      # For a response body of:
+      #
+      #     {
+      #       character: {
+      #         id: 1,
+      #         name: 'Finn The Human'
+      #       }
+      #     }
+      #
+      # @param name [Symbol] the name of the response field
+      # @param description [String] a description of the response field
+      # @param scope [Symbol, Array<Symbol>] how the field is scoped
+      # @param type [String]
+      # @return [void]
       def field(name, description, scope: [], type: nil)
         metadata[METADATA_NAMESPACE][:fields] ||= {}
         metadata[METADATA_NAMESPACE][:fields][name] = {
@@ -32,6 +84,25 @@ module RspecApiDocs
         }
       end
 
+      # For setting params of a request.
+      #
+      # Usage:
+      #
+      #     doc do
+      #       param :id, 'The id of a character', required: true
+      #       param :name, 'A tag on a character', scope: :tag
+      #     end
+      #
+      # For a path of:
+      #
+      #     /characters/:id?tag[name]=:name
+      #
+      # @param name [Symbol] the name of the parameter
+      # @param description [String] a description of the parameter
+      # @param scope [Symbol, Array<Symbol>] how the parameter is scoped
+      # @param type [String]
+      # @param required [true, false] if the field is required
+      # @return [void]
       def param(name, description, scope: [], type: nil, required: false)
         metadata[METADATA_NAMESPACE][:parameters] ||= {}
         metadata[METADATA_NAMESPACE][:parameters][name] = {

data/lib/rspec_api_docs/dsl/request_store.rb

@@ -1,5 +1,6 @@
 module RspecApiDocs
   module Dsl
+    # Used to store request/response pairs.
     class RequestStore
       attr_reader :metadata
 
@@ -7,6 +8,26 @@ module RspecApiDocs
         @metadata = example.metadata
       end
 
+      # Only needed if you need to store multiple requests for a single example.
+      #
+      # Usage:
+      #
+      #     it 'stores the requests a character' do
+      #       doc do
+      #         explanation 'Creating and requesting a character'
+      #       end
+      #
+      #       post '/characters', {name: 'Finn The Human'}
+      #
+      #       doc << [last_request, last_response]
+      #
+      #       get '/characters/1'
+      #
+      #       # The last request/response pair is stored automatically
+      #     end
+      #
+      # @param value [Array<Rack::Request, Rack::Response>] an array of a request and response object
+      # @return [void]
       def <<(value)
         metadata[METADATA_NAMESPACE][:requests] ||= []
         metadata[METADATA_NAMESPACE][:requests] << value.sort_by { |v| v.class.name }.reverse

data/lib/rspec_api_docs/formatter.rb

@@ -1,27 +1,65 @@
 require 'rspec/core/formatters/base_formatter'
-require 'json'
 
+require 'rspec_api_docs'
 require 'rspec_api_docs/formatter/resource'
-require 'rspec_api_docs/formatter/renderers/json_renderer'
+require 'rspec_api_docs/formatter/renderer/json_renderer'
+require 'rspec_api_docs/formatter/renderer/raddocs_renderer'
+require 'rspec_api_docs/formatter/renderer/slate_renderer'
 
 module RspecApiDocs
+  # Unknown renderer configured.
+  UnknownRenderer = Class.new(BaseError)
+
+  # The RSpec formatter.
+  #
+  # Usage:
+  #
+  #     rspec --format=RspecApiDocs::Formatter
   class Formatter < RSpec::Core::Formatters::BaseFormatter
     RSpec::Core::Formatters.register self, :example_passed, :close
 
     attr_reader :resources
 
     def initialize(*args)
-      @resources = []
+      @resources = {}
       super args
     end
 
+    # Initializes and stores {Resource}s.
+    #
+    # @return [void]
     def example_passed(example_notification)
-      return unless example_notification.example.metadata[METADATA_NAMESPACE]
-      resources << Resource.new(example_notification.example)
+      rspec_example = example_notification.example
+      return unless rspec_example.metadata[METADATA_NAMESPACE]
+      resource = Resource.new(rspec_example)
+      resources[resource.name] ||= resource
+      resources[resource.name].examples << Resource::Example.new(rspec_example)
     end
 
+    # Calls the configured renderer with the stored {Resource}s.
+    #
+    # @return [void]
     def close(null_notification)
-      JSONRender.new(resources).render
+      renderer.new(resources.values).render
+    end
+
+    private
+
+    def renderer
+      value = RspecApiDocs.configuration.renderer
+
+      case value
+      when :json
+        Renderer::JSONRenderer
+      when :raddocs
+        Renderer::RaddocsRenderer
+      when :slate
+        Renderer::SlateRenderer
+      when Class
+        value
+      else
+        raise UnknownRenderer, "unknown renderer #{value.inspect}"
+      end
     end
   end
 end

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

@@ -0,0 +1,35 @@
+require 'json'
+require 'rspec_api_docs/formatter/renderer/json_renderer/name'
+require 'rspec_api_docs/formatter/renderer/json_renderer/resource_serializer'
+
+module RspecApiDocs
+  module Renderer
+    class JSONRenderer
+      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 JSON.pretty_generate(output) + "\n"
+        end
+      end
+
+      private
+
+      def output
+        resources.map do |resource|
+          ResourceSerializer.new(resource).to_h
+        end
+      end
+
+      def output_file
+        Pathname.new(RspecApiDocs.configuration.output_dir) + 'index.json'
+      end
+    end
+  end
+end

data/lib/rspec_api_docs/formatter/renderer/json_renderer/example_serializer.rb

@@ -0,0 +1,47 @@
+module RspecApiDocs
+  module Renderer
+    class JSONRenderer
+      class ExampleSerializer
+        attr_reader :example
+
+        def initialize(example)
+          @example = example
+        end
+
+        def to_h # rubocop:disable Metrics/AbcSize
+          {
+            description: example.description,
+            name: example.name,
+            httpMethod: example.http_method,
+            parameters: parameters(example.parameters),
+            path: example.path,
+            requests: example.requests,
+            responseFields: response_fields(example.response_fields),
+          }
+        end
+
+        private
+
+        def parameters(parameters)
+          parameters.map do |parameter|
+            {
+              name: Name.(name: parameter.name, scope: parameter.scope),
+              description: parameter.description,
+              required: parameter.required,
+            }
+          end
+        end
+
+        def response_fields(fields)
+          fields.map do |field|
+            {
+              name: Name.(name: field.name, scope: field.scope),
+              description: field.description,
+              type: field.type,
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec_api_docs/formatter/renderer/json_renderer/name.rb

@@ -0,0 +1,18 @@
+module RspecApiDocs
+  module Renderer
+    class JSONRenderer
+      class Name
+        def self.call(name:, scope:)
+          scope = Array(scope)
+          if scope.empty?
+            name
+          else
+            scope.each_with_index.inject('') do |str, (part, index)|
+              str << (index == 0 ? part : "[#{part}]").to_s
+            end + "[#{name}]"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+require 'rspec_api_docs/formatter/renderer/json_renderer/example_serializer'
+
+module RspecApiDocs
+  module Renderer
+    class JSONRenderer
+      class ResourceSerializer
+        attr_reader :resource
+
+        def initialize(resource)
+          @resource = resource
+        end
+
+        def to_h
+          {
+            name: resource.name,
+            description: resource.description,
+            examples: examples,
+          }
+        end
+
+        private
+
+        def examples
+          resource.examples.map do |example|
+            ExampleSerializer.new(example).to_h
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+require 'json'
+
+require 'rspec_api_docs/formatter/renderer/raddocs_renderer/index_serializer'
+require 'rspec_api_docs/formatter/renderer/raddocs_renderer/link'
+require 'rspec_api_docs/formatter/renderer/raddocs_renderer/resource_serializer'
+
+module RspecApiDocs
+  module Renderer
+    class RaddocsRenderer
+      attr_reader :resources
+
+      def initialize(resources)
+        @resources = resources
+      end
+
+      def render
+        write_index
+        write_examples
+      end
+
+      private
+
+      def write_index
+        FileUtils.mkdir_p output_dir
+
+        File.open(output_dir + 'index.json', 'w') do |f|
+          f.write JSON.pretty_generate(IndexSerializer.new(resources).to_h) + "\n"
+        end
+      end
+
+      def write_examples
+        resources.each do |resource|
+          resource.examples.each do |example|
+            write_example(resource, example)
+          end
+        end
+      end
+
+      def write_example(resource, example)
+        FileUtils.mkdir_p file(resource, example).dirname
+
+        File.open(file(resource, example), 'w') do |f|
+          f.write JSON.pretty_generate(ResourceSerializer.new(resource, example).to_h) + "\n"
+        end
+      end
+
+      def output_dir
+        Pathname.new RspecApiDocs.configuration.output_dir
+      end
+
+      def file(resource, example)
+        output_dir + Link.(resource.name, example.name)
+      end
+    end
+  end
+end