rspec-api-blueprint-formatter 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: caa97c97bdc0ff1c45846a5d0941f76ff950e483
-  data.tar.gz: 333ffb493e1e9289ae840e13f22b63e1cdb7860e
+  metadata.gz: e639084209b7c2eb7969f4bf4472bde50b48b7ca
+  data.tar.gz: d3498d9b1ee41bcbaf92b0345b1700bc8749db04
 SHA512:
-  metadata.gz: df31b52419a0594e5e3868648fb626267206e6788aaa8bf280f3781b4254e1d49c2dff1ce760f06e19fd6a32bec1d68ed8ce186a5250bf38982951330515ed15
-  data.tar.gz: 5fce90486bb6df004c785313aaea5cab8081a8383e5a1017c3e572611078d302ac6075a4f43b003b7bacfd969368478d0ef0a6bcdafd1def6aa26b85d099fe23
+  metadata.gz: 7e79fc9af3465c1bc7fc329d440fa8635b56445a83c0a9e3f8cc9f0c19fdefffba87f006dbfa4e4ff0972ab9cbe477ebfa660ab929cebe7dfce61e5f5d4ee0ea
+  data.tar.gz: 871449a2bc0e3d2f8a22e47dc260e4a4b720bb4261dc53dfeed9e1b90db9ea98f8ad0a1f4f0fcf82bf4c71001f2d500a9c15470c6789d4245a166dca0b8791ba

data/lib/api_blueprint.rb

@@ -1,8 +1,12 @@
 require 'rspec'
 require 'rspec/core/formatters/base_formatter'
 
+require 'api_blueprint/version'
+require 'api_blueprint/base_formatter'
+require 'api_blueprint/example_formatter'
+require 'api_blueprint/action_formatter'
+
 class ApiBlueprint < RSpec::Core::Formatters::BaseFormatter
-  VERSION = "0.1.3"
   RSpec::Core::Formatters.register self, :example_passed, :example_started, :stop
 
   def initialize(output)
@@ -34,6 +38,7 @@ class ApiBlueprint < RSpec::Core::Formatters::BaseFormatter
           metadata[:resource] => {
             metadata[:action] => {
               description: metadata[:action_description],
+              parameters: metadata[:action_parameters],
               examples: {
                 description => {
                   request: {
@@ -84,30 +89,14 @@ class ApiBlueprint < RSpec::Core::Formatters::BaseFormatter
     actions.each &method(:print_action)
   end
 
-  def print_action(action_name, action_meta_data)
-    output.puts "## #{action_name}\n" \
-                "\n" \
-                "#{action_meta_data[:description]}\n" \
-                "\n" \
+  def print_action(action_name, action_metadata)
+    output.puts ApiBlueprintFormatter::ActionFormatter.new(action_name, action_metadata).format
 
-    action_meta_data[:examples].each &method(:print_example)
+    action_metadata[:examples].each &method(:print_example)
   end
 
   def print_example(example_description, example_metadata)
-    output.puts "+ Request #{example_description}\n" \
-      "\n" \
-      "        #{example_metadata[:request][:parameters]}\n" \
-      "        \n" \
-      "        Location: #{example_metadata[:location]}\n" \
-      "        Source code:\n" \
-      "        \n" \
-      "#{indent_lines(8, example_metadata[:source])}\n" \
-      "\n"
-
-    output.puts "+ Response #{example_metadata[:response][:status]} (#{example_metadata[:request][:format]})\n" \
-      "\n" \
-      "        #{example_metadata[:response][:body]}\n" \
-      "\n"
+    output.puts ApiBlueprintFormatter::ExampleFormatter.new(example_description, example_metadata).format
   end
 
   # To include the descriptions of all the contexts that are below the action
@@ -121,11 +110,4 @@ class ApiBlueprint < RSpec::Core::Formatters::BaseFormatter
       [example_metadata[:description]] + description_array_from(parent)
     end
   end
-
-  def indent_lines(number_of_spaces, string)
-    string
-      .split("\n")
-      .map { |a| a.prepend(' ' * number_of_spaces) }
-      .join("\n")
-  end
 end

data/lib/api_blueprint/action_formatter.rb

@@ -0,0 +1,93 @@
+module ApiBlueprintFormatter
+  # Parses example metadata for Actions and outputs markdown in
+  # accordance with the API Blueprint spec.
+  #
+  # Spec: https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def-action-section
+  class ActionFormatter < BaseFormatter
+    attr_reader :action_metadata, :action_name
+
+    def initialize(action_name, action_metadata)
+      @action_name = action_name
+      @action_metadata = action_metadata
+      @parameters = action_metadata[:parameters] || []
+    end
+
+    def format
+      output = []
+      output << "## #{action_name}"
+      output << ''
+      output << action_metadata[:description].to_s
+      output << ''
+      output += format_parameters
+      output << ''
+
+      output.join("\n")
+    end
+
+    private
+
+    def format_parameters
+      return [] if @parameters.empty?
+
+      output = ['']
+      output << '+ Parameters'
+      @parameters.each_pair do |param, data|
+        output += format_param(param, data)
+      end
+      output << ''
+
+          output
+    end
+
+    def format_param(param, data)
+      out = []
+      out << indent_lines(4, action_header(param, data))
+
+      if multiline_description(param)
+        out << ''
+        out << indent_lines(8, data[:description])
+        out << ''
+      end
+
+      out << indent_lines(8, "+ Default: #{data[:default]}") if data[:default]
+      out += format_members(param)
+
+      out
+    end
+
+    def multiline_description(param)
+      members(param).size > 0
+    end
+
+    def action_header(param, data)
+      param_signature = "#{param}#{param_attributes_string(data)}"
+      multiline_description = !members(param).empty?
+
+      header = "+ #{param_signature}"
+      header += " - #{data[:description]}" unless multiline_description
+      header
+    end
+
+    def param_attributes_string(data)
+      optional = data[:optional] ? 'optional' : nil
+      param_attributes = [data[:type], optional].compact
+
+      " (#{param_attributes.join(', ')})" unless param_attributes.empty?
+    end
+
+    def members(param)
+      @action_metadata[:parameters][param].fetch(:members, [])
+    end
+
+    def format_members(param)
+      out = []
+      unless members(param).empty?
+        out << indent_lines(8, '+ Members')
+        members(param).each do |member|
+          out << indent_lines(12, "+ `#{member}`")
+        end
+      end
+      out
+    end
+  end
+end

data/lib/api_blueprint/base_formatter.rb

@@ -0,0 +1,20 @@
+module ApiBlueprintFormatter
+  # Base for other formatters, providing utility methods
+  class BaseFormatter
+    protected
+
+    def indent_lines(number_of_spaces, string)
+      string
+        .split("\n")
+        .map { |a| a.prepend(' ' * number_of_spaces) }
+        .join("\n")
+    end
+
+    # Change certain characters that might come up in example names
+    # but do not play well with the API specs.
+    # Example: 'Test for [value]' -> 'Test for {value}'
+    def sanitize_api_identifier(name)
+      name.gsub(/[\[\]]/, '[' => '{', ']' => '}')
+    end
+  end
+end

data/lib/api_blueprint/example_formatter.rb

@@ -0,0 +1,47 @@
+module ApiBlueprintFormatter
+  # Parses example metadata for Examples (Request+Response) and outputs
+  # markdown in accordance with the API Blueprint spec.
+  #
+  # Specs:
+  #   - https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def-request-section
+  #   - https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#response-section
+  class ExampleFormatter < BaseFormatter
+    attr_reader :example_metadata
+
+    def initialize(example_description, example_metadata)
+      @example_description = example_description
+      @example_metadata = example_metadata
+    end
+
+    def format
+      out = ''
+      out << format_request
+      out << format_response
+    end
+
+    def example_description
+      sanitize_api_identifier(@example_description)
+    end
+
+    private
+
+    def format_request
+      "+ Request #{example_description}\n" \
+      "\n" \
+      "        #{example_metadata[:request][:parameters]}\n" \
+      "\n" \
+      "        Location: #{example_metadata[:location]}\n" \
+      "        Source code:\n" \
+      "\n" \
+      "#{indent_lines(8, example_metadata[:source])}\n" \
+      "\n"
+    end
+
+    def format_response
+      "+ Response #{example_metadata[:response][:status]} (#{example_metadata[:request][:format]})\n" \
+      "\n" \
+      "        #{example_metadata[:response][:body]}\n" \
+      "\n"
+    end
+  end
+end

data/lib/api_blueprint/version.rb

@@ -0,0 +1,3 @@
+module ApiBlueprintFormatter
+  VERSION = '0.2.0'
+end

data/spec/api_blueprint/action_formatter_spec.rb

@@ -0,0 +1,123 @@
+require 'spec_helper'
+
+require 'json'
+
+RSpec.describe ApiBlueprintFormatter::ActionFormatter do
+  subject { described_class.new(action_name, action_metadata).format }
+
+  let(:action_name) { 'Standard Action [GET /api/v0/resource]' }
+  let(:action_metadata) { { description: action_description, parameters: action_parameters } }
+
+  let(:action_description) { 'Lorem ipsum et dolor' }
+  let(:action_parameters) { {} }
+
+  describe '#format' do
+    context 'with standard meta-data' do
+      it 'formats properly' do
+        is_expected.to eq "## Standard Action [GET /api/v0/resource]\n\nLorem ipsum et dolor\n\n"
+      end
+    end
+
+    context 'with parameters' do
+      let(:action_header) { "## #{action_name}\n\n#{action_description}\n" }
+
+      context 'only descriptive params' do
+        let(:action_parameters) do
+          {
+            id: { description: 'Id of a post' }
+          }
+        end
+
+        it do
+          is_expected.to eq <<-EOF
+#{action_header}
+
++ Parameters
+    + id - Id of a post
+
+          EOF
+        end
+      end
+
+      context 'descriptive param with type' do
+        let(:action_parameters) do
+          {
+            id: { description: 'Id of a post', type: :number }
+          }
+        end
+
+        it do
+          is_expected.to eq <<-EOF
+#{action_header}
+
++ Parameters
+    + id (number) - Id of a post
+
+          EOF
+        end
+      end
+
+      context 'descriptive param with type and optionality' do
+        let(:action_parameters) do
+          {
+            amount: { description: 'Id of a post', type: :number, optional: true }
+          }
+        end
+
+        it do
+          is_expected.to eq <<-EOF
+#{action_header}
+
++ Parameters
+    + amount (number, optional) - Id of a post
+
+          EOF
+        end
+      end
+
+      context 'descriptive param with: type, optionality, default value' do
+        let(:action_parameters) do
+          {
+            amount: { description: 'Id of a post', type: :number, optional: true, default: 0 }
+          }
+        end
+
+        it do
+          is_expected.to eq <<-EOF
+#{action_header}
+
++ Parameters
+    + amount (number, optional) - Id of a post
+        + Default: 0
+
+          EOF
+        end
+      end
+
+      context 'descriptive param with: enum and members' do
+        let(:action_parameters) do
+          {
+            id: { description: 'Id of a post', type: 'enum[string]', members: %w(A B C) }
+          }
+        end
+
+        it do
+          is_expected.to eq <<-EOF
+#{action_header}
+
++ Parameters
+    + id (enum[string])
+
+        Id of a post
+
+        + Members
+            + `A`
+            + `B`
+            + `C`
+
+          EOF
+        end
+      end
+    end
+  end
+end

data/spec/api_blueprint/example_formatter_spec.rb

@@ -0,0 +1,87 @@
+require 'spec_helper'
+
+require 'json'
+
+RSpec.describe ApiBlueprintFormatter::ExampleFormatter do
+  subject { described_class.new(example_description, example_metadata).format }
+
+  let(:example_description) { "Standard Request" }
+  let(:example_metadata) do
+    {
+        request: request_metadata,
+        response: response_metadata,
+        location: location,
+        source: source
+    }
+  end
+
+  let(:request_metadata) { { parameters: {}, format: 'application/json' } }
+  let(:response_metadata) { { status: 200, body: JSON.generate({a:1, b:2, c:3}) } }
+  let(:location) { "spec/api_blueprint/example_formatter_spec.rb" }
+  let(:source) { "it 'returns standard APi Blueprint format' do\n  ;\nend" }
+
+
+  describe '#format' do
+    context 'with standard meta-data' do
+      it 'formats properly' do
+        is_expected.to eq <<EOF
++ Request Standard Request
+
+        {}
+
+        Location: spec/api_blueprint/example_formatter_spec.rb
+        Source code:
+
+        it 'returns standard APi Blueprint format' do
+          ;
+        end
+
++ Response 200 (application/json)
+
+        {"a":1,"b":2,"c":3}
+
+EOF
+      end
+
+      context 'and with parameters' do
+        context 'from request data' do
+          let(:request_metadata) { { parameters: {'p1': 'v1', 'p2': 'v2'}, format: 'application/json' } }
+
+          it 'formats properly' do
+            is_expected.to eq <<EOF
++ Request Standard Request
+
+        {:p1=>"v1", :p2=>"v2"}
+
+        Location: spec/api_blueprint/example_formatter_spec.rb
+        Source code:
+
+        it 'returns standard APi Blueprint format' do
+          ;
+        end
+
++ Response 200 (application/json)
+
+        {"a":1,"b":2,"c":3}
+
+EOF
+          end
+
+        end
+      end
+     end
+  end
+
+  describe '#example_description' do
+    subject { described_class.new(example_description, example_metadata).example_description }
+
+    context 'when description has non-compliant characters' do
+      let(:example_description) { 'Standard Request for [company]' }
+
+      it 'changes [] to {}' do
+        expect(subject).to eq 'Standard Request for {company}'
+      end
+    end
+  end
+
+end

data/spec/rspec/api/blueprint/formatter_spec.rb

@@ -1,7 +1,7 @@
 require 'spec_helper'
 
-describe ApiBlueprint do
+describe ApiBlueprintFormatter do
   it 'has a version number' do
-    expect(ApiBlueprint::VERSION).not_to be nil
+    expect(ApiBlueprintFormatter::VERSION).not_to be nil
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-api-blueprint-formatter
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Nam Chu Hoai
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-01 00:00:00.000000000 Z
+date: 2016-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -64,6 +64,12 @@ files:
 - bin/console
 - bin/setup
 - lib/api_blueprint.rb
+- lib/api_blueprint/action_formatter.rb
+- lib/api_blueprint/base_formatter.rb
+- lib/api_blueprint/example_formatter.rb
+- lib/api_blueprint/version.rb
+- spec/api_blueprint/action_formatter_spec.rb
+- spec/api_blueprint/example_formatter_spec.rb
 - spec/rspec/api/blueprint/formatter_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/nambrot/rspec-api-blueprint-formatter
@@ -92,6 +98,8 @@ signing_key:
 specification_version: 4
 summary: Use your Rspec tests to build your API documentation
 test_files:
+- spec/api_blueprint/action_formatter_spec.rb
+- spec/api_blueprint/example_formatter_spec.rb
 - spec/rspec/api/blueprint/formatter_spec.rb
 - spec/spec_helper.rb
 has_rdoc: