td_rspec-api-blueprint-formatter 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 59a8e91cd531a25b3b19452d5dce0beef7f3f22d
+  data.tar.gz: 49503ca3349755f31f1caf88a65c0c1c175db506
+SHA512:
+  metadata.gz: 2933fc8ed8472b06ffd1874537fd4771a2e1f8b0225469cf51d0657772479197db49a6770dda24ebe52ee53e40af5443c7be5f08c9353455e045a50ce4e7cb66
+  data.tar.gz: 2715f7b0116bad33ef7d8bdc189d812917d60e77cddb683ffc7237d375d36fb4ca8ee56759b081bc9d7007d8cc3538fa8b617e1bb1d769c1579fdc9b3e8e4817

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'api_blueprint_formatter'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/api_blueprint.rb

@@ -0,0 +1,4 @@
+require_relative 'api_blueprint/rspec_formatter'
+
+# keeping reference for backwards compatibility
+ApiBlueprint = APIBlueprint::RspecFormatter

data/lib/api_blueprint/configurable.rb

@@ -0,0 +1,21 @@
+module APIBlueprint
+  module Configurable
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= default_configuration
+    end
+
+    def reset_configuration!
+      @configuration = default_configuration
+    end
+
+    def default_configuration
+      configuration = Configuration.new
+      configuration.output_source = true
+      configuration
+    end
+  end
+end

data/lib/api_blueprint/configuration.rb

@@ -0,0 +1,5 @@
+module APIBlueprint
+  class Configuration
+    attr_accessor :output_source
+  end
+end

data/lib/api_blueprint/output_collector.rb

@@ -0,0 +1,84 @@
+module APIBlueprint
+  # Collects example for API documentation
+  class OutputCollector
+    attr_accessor :resources, :resource_parameters, :configuration
+
+    def initialize(configuration)
+      @configuration = configuration
+      @resources = {}
+      @resource_parameters = {}
+    end
+
+    def add_example(metadata, example_block, request, response)
+      @resources.deep_merge!(
+        metadata[:resource_group] => build_resource(example_block, metadata,
+                                                    request, response)
+      )
+    end
+
+    private
+
+    def build_resource(example_block, metadata, request, response)
+      @resource_parameters[metadata[:resource]] = metadata[:resource_parameters]
+
+      {
+        metadata[:resource] => {
+          metadata[:action] => build_action(example_block, metadata, request,
+                                            response)
+        }
+      }
+    end
+
+    def build_action(example_block, metadata, request, response)
+      example_description = metadata[:example_description] ||
+        metadata[:description].tr('()', '/')
+
+      {
+        description: metadata[:action_description],
+        examples: {
+          example_description => build_example(example_block, metadata,
+                                               request, response)
+        }
+      }
+    end
+
+    def build_example(example_block, metadata, request, response)
+      {
+        request: build_request(request),
+        source: example_block.source,
+        location: metadata[:location],
+        response: build_response(response)
+      }
+    end
+
+    def build_request(request)
+      {
+        parameters: request_parameters(request),
+        format: request.format
+      }
+    end
+
+    def request_parameters(request)
+      path_params = request.path_parameters.keys.map(&:to_s)
+      request.parameters.except(*path_params).to_json
+    rescue Encoding::UndefinedConversionError
+      'binary'
+    end
+
+    def build_response(response)
+      {
+        status: response.status,
+        content_type: response.content_type.to_s,
+        body: response_body(response)
+      }
+    end
+
+    def response_body(response)
+      if response['Content-Transfer-Encoding'] == 'binary'
+        'binary'
+      else
+        response.body
+      end
+    end
+  end
+end

data/lib/api_blueprint/output_printer.rb

@@ -0,0 +1,118 @@
+module APIBlueprint
+  # Prints API blueprint output
+  class OutputPrinter
+    attr_accessor :configuration, :examples, :output
+
+    def initialize(configuration, output_collector, output)
+      @configuration = configuration
+      @output_collector = output_collector
+      @output = output
+    end
+
+    def print
+      sorted_examples.each do |resource_group_name, resource_group_resources|
+        print_resource_group(resource_group_name, resource_group_resources)
+      end
+    end
+
+    private
+
+    def print_resource_group(resource_group_name, resource_group_resources)
+      output.puts "# Group #{resource_group_name}"
+      resource_group_resources.each(&method(:print_resource))
+    end
+
+    def sorted_examples
+      @output_collector.resources.sort_by { |k, _v| k }
+    end
+
+    def print_resource(resource_name, actions)
+      validate_resource_name(resource_name)
+
+      output.puts "# #{resource_name}"
+
+      print_resource_parameters(resource_name)
+
+      validate_http_verbs(actions, resource_name)
+
+      actions.each(&method(:print_action))
+    end
+
+    def validate_http_verbs(actions, resource_name)
+      http_verbs = actions.keys.map do |action|
+        action.scan(/\[([A-Z]+)\]/).flatten[0]
+      end
+
+      return if http_verbs.length == http_verbs.uniq.length
+
+      raise "Action HTTP verbs are not unique #{actions.keys.inspect} for "\
+            "resource: '#{resource_name}'"
+    end
+
+    def validate_resource_name(resource_name)
+      return if resource_name =~ %r{^[^\[\]]*\[/[^\]]+\]}
+      raise "resource: '#{resource_name}' is invalid. :resource needs to be "\
+          'specified according to https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#resource-section'
+    end
+
+    def print_action(action_name, action_meta_data)
+      output.puts "## #{action_name}\n" \
+                "\n" \
+                "#{action_meta_data[:description]}\n" \
+                "\n" \
+
+      action_meta_data[:examples].each(&method(:print_example))
+    end
+
+    def print_example(example_description, example_metadata)
+      print_request(example_description, example_metadata)
+      print_source(example_metadata)
+      print_response(example_metadata)
+    end
+
+    def print_resource_parameters(resource_name)
+      return unless @output_collector.resource_parameters[resource_name]
+
+      output.puts "\n"
+      output.puts '+ Parameters'
+
+      @output_collector.resource_parameters[resource_name].each do |param, desc|
+        output.puts "    + #{param} #{desc}\n"
+      end
+
+      output.puts "\n"
+    end
+
+    def print_request(example_description, example_metadata)
+      output.puts "+ Request #{example_description}\n" \
+                  "\n" \
+                  "        #{example_metadata[:request][:parameters]}\n" \
+                  "        \n"
+    end
+
+    def print_source(example_metadata)
+      return if @configuration.output_source
+
+      output.puts "        Location: #{example_metadata[:location]}\n" \
+                  "        Source code:\n" \
+                  "        \n" \
+                  "#{indent_lines(8, example_metadata[:source])}\n" \
+                  "\n"
+    end
+
+    def print_response(example_metadata)
+      output.puts "+ Response #{example_metadata[:response][:status]} "\
+                  "(#{example_metadata[:response][:content_type]})\n" \
+                  "\n" \
+                  "        #{example_metadata[:response][:body]}\n" \
+                  "\n"
+    end
+
+    def indent_lines(number_of_spaces, string)
+      string
+        .split("\n")
+        .map { |a| a.prepend(' ' * number_of_spaces) }
+        .join("\n")
+    end
+  end
+end

data/lib/api_blueprint/rspec_formatter.rb

@@ -0,0 +1,60 @@
+require 'rspec/core/formatters'
+require 'rspec/core/formatters/base_formatter'
+
+require_relative 'output_collector'
+require_relative 'output_printer'
+require_relative 'configurable'
+require_relative 'configuration'
+
+module APIBlueprint
+  # RSpec formatter for API blueprint
+  class RspecFormatter < RSpec::Core::Formatters::BaseFormatter
+    VERSION = '0.1.0'.freeze
+
+    extend Configurable
+
+    RSpec::Core::Formatters.register self, :example_passed, :example_started,
+                                     :stop
+
+    def initialize(output)
+      super
+
+      configure_rspec
+
+      @output_collector = OutputCollector.new(configuration)
+    end
+
+    def example_started(notification)
+      @example_group_instance = notification.example.example_group_instance
+    end
+
+    def example_passed(passed)
+      metadata = passed.example.metadata
+
+      if metadata[:apidoc] && metadata[:resource_group] &&
+         metadata[:resource] && metadata[:action] &&
+         metadata[:action_description]
+
+        @output_collector
+          .add_example(metadata,
+                       passed.example.instance_variable_get(:@example_block),
+                       @example_group_instance.request,
+                       @example_group_instance.response)
+      end
+    end
+
+    def stop(_notification)
+      OutputPrinter.new(configuration, @output_collector, output).print
+    end
+
+    private
+
+    def configure_rspec
+      RSpec.configuration.silence_filter_announcements = true
+    end
+
+    def configuration
+      self.class.configuration
+    end
+  end
+end

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

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

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'api_blueprint'

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: td_rspec-api-blueprint-formatter
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Nam Chu Hoai
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-12-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.45'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.45'
+description: Use your Rspec tests to build your API documentation
+email:
+- nambrot@googlemail.com
+executables:
+- console
+- setup
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/console
+- bin/setup
+- lib/api_blueprint.rb
+- lib/api_blueprint/configurable.rb
+- lib/api_blueprint/configuration.rb
+- lib/api_blueprint/output_collector.rb
+- lib/api_blueprint/output_printer.rb
+- lib/api_blueprint/rspec_formatter.rb
+- spec/rspec/api/blueprint/formatter_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/nambrot/rspec-api-blueprint-formatter
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Use your Rspec tests to build your API documentation
+test_files:
+- spec/rspec/api/blueprint/formatter_spec.rb
+- spec/spec_helper.rb