apitecto 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bd83508eada2e33298523b90167c48faa0bcd81d
+  data.tar.gz: b8cefda97c4f6f322c5574299a12738d470deca5
+SHA512:
+  metadata.gz: 2a2fa4f1116f036edac8c3e6bf42305024361e631ad58208a5f51249e3ab2a1329f0d42ffeae464593b71220d2a5aab07fd604329678d8726d69f7bb8ce60c9e
+  data.tar.gz: 3b0ffd44e28c115e7fcc07870b4c1fdaf8f4a8b6c0ee2820cdef244c251582a35729925973c6867509c4cf649f0282ad2dd1bb6c5c3c784e41223300cc0e14c3

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.0.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in apitecto.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Roberto Quintanilla
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,31 @@
+# Apitecto
+
+TODO: Write a gem description
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'apitecto'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install apitecto
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+1. Fork it ( https://github.com/vovimayhem/apitecto/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+

data/apitecto.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'apitecto/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "apitecto"
+  spec.version       = Apitecto::VERSION
+  spec.authors       = ["Roberto Quintanilla"]
+  spec.email         = ["roberto.quintanilla@gmail.com"]
+  spec.summary       = %q{A ruby library for generating REST Api documentation using API Blueprint}
+  spec.description   = %q{A ruby library for generating REST Api documentation using API Blueprint}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "matter_compiler", "~> 0.5"
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+end

data/lib/apitecto.rb

@@ -0,0 +1,304 @@
+require "apitecto/version"
+require "matter_compiler/blueprint"
+
+module Apitecto
+  mattr_reader    :blueprints, :lines_of_spec
+  mattr_accessor  :output_dir
+  
+  def self.blueprints; @@blueprints ||= {}; end
+  def self.blueprint_exists?(blueprint_name); blueprints.has_key?(blueprint_name); end
+
+
+  def self.lines_of_spec; @@lines_of_spec ||= {}; end
+  def self.get_lines_of_spec(spec_file_path)
+    unless lines_of_spec[spec_file_path].present?
+      lines_of_spec[spec_file_path] = File.read(spec_file_path).each_line.to_a.map(&:strip).inject({}) do |lines, line|
+        lines[lines.values.count + 1] = (line =~ /\A#/i || line == "") ? (line == "" ? "" : line[1..-1]) : nil
+        lines
+      end
+    end
+    lines_of_spec[spec_file_path]
+  end
+end
+
+RSpec.configure do |config|
+
+  config.before(:suite) do
+    Apitecto.output_dir = File.join((defined?(Rails) ? Rails.root : File.expand_path('.')), 'doc')
+  end
+
+  # Formar el AST de Blueprint a partir de los examples de request...
+  config.after(:each, type: :request) do |rspec_example|
+
+    if rspec_example.metadata[:rest_api_name].present?
+
+      ################################################################################################
+      #
+      lines_of_spec = Apitecto.get_lines_of_spec rspec_example.metadata[:file_path]
+      
+      ##############################################################################
+      # Find or create the Root AST node:
+      rest_api_name = rspec_example.metadata[:rest_api_name] || :default
+      rest_api_key = rest_api_name.to_s.downcase.split.join("-").dasherize
+
+      blueprint_ast = if Apitecto.blueprint_exists? rest_api_key
+        Apitecto.blueprints[rest_api_key]
+      else
+        Apitecto.blueprints[rest_api_key] = { name: rest_api_name, description: nil, resourceGroups: [] }
+      end
+
+      blueprint_ast[:description] = blueprint_ast[:description] || rspec_example.metadata[:rest_api_description]
+
+      ##############################################################################################
+      # Find the rspec_example's Example Groups metadata mappable to 
+      # API Blueprint's Resource Group, Resource and Action:
+      rspec_action_metadata         = rspec_example.metadata[:example_group]
+      rspec_resource_metadata       = rspec_action_metadata[:parent_example_group]
+      rspec_resource_group_metadata = rspec_resource_metadata[:parent_example_group]
+
+      ##############################################################################################
+      # Retrieve or form the resource group AST:
+      
+      # ...find:
+      resource_group_ast = blueprint_ast[:resourceGroups].detect do |resource_group| 
+        resource_group[:rspec_file_path] == rspec_resource_group_metadata[:file_path]
+      end
+
+      # ...create unless found:
+      unless resource_group_ast.present?
+        resource_group_comment_end_line_number = rspec_resource_group_metadata[:line_number]
+        resource_group_comment_start_line_number = resource_group_comment_end_line_number
+        while (!lines_of_spec[resource_group_comment_start_line_number-1].nil?) do
+          resource_group_comment_start_line_number -= 1
+        end
+
+        resource_group_comment_range = resource_group_comment_start_line_number..resource_group_comment_end_line_number
+        resource_group_comment_lines = lines_of_spec.select { |key| resource_group_comment_range.include? key }.values.compact
+        
+        resource_group_name = resource_group_comment_lines.detect { |line| line =~ /\A#\s+(.+)/i }
+        resource_group_name = $1 unless resource_group_name.blank?
+        resource_group_name = rspec_resource_group_metadata[:description] unless resource_group_name.present?
+
+        resource_group_description = resource_group_comment_lines.select { |line| line !~ /\A#|\s+\+/i }.map(&:strip)
+        resource_group_description.shift  if resource_group_description.first.blank?
+        resource_group_description.pop    if resource_group_description.last.blank?
+        resource_group_description = resource_group_description.join("\n")
+
+        resource_group_sort_order = rspec_resource_group_metadata[:doc_sort_order] || 90000000000000
+
+        blueprint_ast[:resourceGroups] << {
+          sort_order:       resource_group_sort_order,                  # Ignored as it's not part of the API Blueprint AST
+          rspec_file_path:  rspec_resource_group_metadata[:file_path],  # Ignored as it's not part of the API Blueprint AST
+          name:             resource_group_name,
+          description:      resource_group_description,
+          resources:        []
+        }
+        resource_group_ast = blueprint_ast[:resourceGroups].last
+      end
+
+      ##############################################################################################
+      # Retrieve or form the example's resource AST:
+      
+      # ...find:
+      resource_ast = resource_group_ast[:resources].detect do |r| 
+        r[:sort_order] == rspec_resource_metadata[:line_number]
+      end
+
+      # ...create unless found:
+      unless resource_ast.present?
+
+        resource_comment_start_line_number = rspec_resource_metadata[:line_number]
+        while (!lines_of_spec[resource_comment_start_line_number-1].nil?) do
+          resource_comment_start_line_number -= 1
+        end
+
+        resource_comment_range = resource_comment_start_line_number..rspec_resource_metadata[:line_number]
+        resource_comment_lines = lines_of_spec.select { |key| resource_comment_range.include? key }.values.compact
+        
+        resource_name         = resource_comment_lines.detect { |line| line =~ /\A#\s+(.+)\[(.+)\]/i }
+        resource_name         = $1.strip unless resource_name.blank?
+        resource_uri_template = $2.strip unless resource_name.blank?
+
+        # Name & UriTemplate last try... rspec example_group metadata:
+        resource_name         = rspec_resource_metadata[:description]   unless resource_name.present?
+        resource_uri_template = rspec_resource_metadata[:uri_template]  unless resource_uri_template.present?
+
+        resource_description = resource_comment_lines.select { |line| line !~ /\A#|\s+\+/i }.map(&:strip)
+        resource_description.shift  if resource_description.first.blank?
+        resource_description.pop    if resource_description.last.blank?
+        resource_description = resource_description.join("\n")
+
+        resource_group_ast[:resources] << {
+          sort_order:   rspec_resource_metadata[:line_number], # Ignored as it's not part of the API Blueprint AST
+          name:         resource_name,
+          description:  resource_description,  # TODO: Extract from somewhere, or default to...
+
+          uriTemplate:  resource_uri_template,
+          model:        nil,  # No Model, as rspec request examples generate some output.
+          parameters:   [],
+          actions:      []
+        }
+
+        resource_ast = resource_group_ast[:resources].last
+      end
+
+      #############################################################################################
+      # Retrieve the rspec example's request & response:
+      request   ||= respond_to?(:last_request)  ? last_request  : @request
+      response  ||= respond_to?(:last_response) ? last_response : @response
+
+      #############################################################################################
+      # Retrieve or form the example's action AST:
+
+      action_ast = resource_ast[:actions].detect { |a| a[:sort_order] == rspec_action_metadata[:line_number] }
+      unless action_ast.present?
+
+        action_comment_start_line_number = rspec_action_metadata[:line_number]
+        while (!lines_of_spec[action_comment_start_line_number-1].nil?) do
+          action_comment_start_line_number -= 1
+        end
+
+        action_comment_range = action_comment_start_line_number..rspec_action_metadata[:line_number]
+        action_comment_lines = lines_of_spec.select { |key| action_comment_range.include? key }.values.compact
+        
+        # 1st try: Group Comments in MD:
+        action_name   = action_comment_lines.detect { |line| line =~ /\A#\s+(.+)\[(.+)\]/i }
+        action_name   = $1.strip unless action_name.blank?
+        action_method = $2.strip unless action_name.blank?
+
+        # 2nd try: extract the method from the RSpec Example Group Metadata's description:
+        action_method = $1.strip if action_method.blank? && rspec_action_metadata[:description] =~ /\A(GET|POST|PUT|PATCH|DELETE)\s/
+
+        # Last try: extract the method from a custom metadata tag:
+        action_method = rspec_action_metadata[:method] if action_method.blank?
+
+        # abort ast if no method was found...
+        if action_method.present?
+          
+          action_description = action_comment_lines.select { |line| line !~ /\A#|\s+\+/i }.map(&:strip)
+          action_description.shift  if action_description.first.blank?
+          action_description.pop    if action_description.last.blank?
+          action_description = action_description.join("\n")
+
+          resource_ast[:actions] << {
+            sort_order:   rspec_action_metadata[:line_number], # Ignored as it's not part of the API Blueprint AST
+            name:         action_name,
+            description:  action_description,
+            method:       action_method,
+            parameters:   [],  # TODO: Extract from somewhere, or default to...
+            examples:     []
+          }
+          action_ast = resource_ast[:actions].last
+        end
+      end
+      
+      if action_ast.present?
+        
+        ##############################################################################################
+        # Form the transaction example AST + add request & response AST's
+        example_comment_start_line_number = rspec_example.metadata[:line_number]
+        while (!lines_of_spec[example_comment_start_line_number-1].nil?) do
+          example_comment_start_line_number -= 1
+        end
+
+        example_comment_range = example_comment_start_line_number..rspec_example.metadata[:line_number]
+        example_comment_lines = lines_of_spec.select { |key| example_comment_range.include? key }.values.compact
+        
+        # 1st try: Group Comments in MD:
+        example_name          = example_comment_lines.detect { |line| line =~ /\A#\s+(.+)\s+\((.+)\)|#\s+(.+)\z/i }
+        example_content_type  = $2.strip if example_name.present? && $2.present?
+        example_name          = ($1 || $3).strip unless example_name.blank?
+
+        # Last try: extract the example_name from the rspec_example metadata description:
+        example_name = rspec_example.metadata[:description] if example_name.blank?
+        example_content_type = request.headers["CONTENT_TYPE"] unless example_content_type.present?
+
+        example_content_type = example_content_type.present? ? "(#{example_content_type})" : ""
+        #example_name = "#{example_name} #{example_content_type}".strip
+
+        example_description = example_comment_lines.select { |line| line !~ /\A#|\s+\+/i }.map(&:strip)
+        example_description.shift  if example_description.first.blank?
+        example_description.pop    if example_description.last.blank?
+        example_description = example_description.join("\n")
+
+        ##############################################################################################
+        # Form the request AST:
+        request_ast = {
+          name:         example_name,
+          description:  example_description,
+          parameters:   [],  # TODO: Extract from somewhere, or default to...
+
+          # Filter headers from the request.headers (env) hash, convert header names:
+          headers:      request.headers.select { |k,v| (k =~ /\AHTTP_/ && k !~ /HOST|COOKIE|USER_AGENT\z/i) || k == "CONTENT_TYPE" }
+                          .map { |k, v| { name: (k == "CONTENT_TYPE" ? k : k[5..-1]).titleize.split().join('-'), value: v } },
+          body:         request.body.read,
+          schema:       nil   # TODO: Extract from somewhere, or default to...
+        }
+
+        ##############################################################################################
+        # Form the response AST Hash:
+
+        response_name = response.status # TODO: el status es sufijo? Se puede agregar mas palabras?
+
+        response_ast  = {
+          name:       response_name,
+          parameters: [],  # TODO: Extract from somewhere, or default to...
+
+          # Assign the response headers
+          # TODO: Filter-out irrelevant headers:
+          headers:    response.headers.select { |k,v| k !~ /\AX-/i && k !~ /Cookie\z/i }
+                        .map { |k, v| { name: k, value: v } },
+          body:       response.body,
+          schema:     nil   # TODO: Extract from somewhere, or default to...
+        }
+
+        #########################################################################################################
+
+        transaction_example_ast = {
+          sort_order:   rspec_example.metadata[:line_number], # Ignored as it's not part of the API Blueprint AST
+          #name:         example_name,
+          #description:  example_description,
+          requests:     [ request_ast   ],
+          responses:    [ response_ast  ]
+        }
+
+        # append the transaction_example_ast
+        action_ast[:examples] << transaction_example_ast
+      end
+    end
+  end
+
+  # Escribir los archivos a partir de los AST's recolectados
+  config.after(:suite) do
+
+    Apitecto.blueprints.each do |api_name, blueprint_ast|
+
+      # RSpec corre los ejemplos en random order (eso es bueno para las pruebas... pero malo para documentacion)
+      # Ordenar los resource groups, resources, actions y examples del AST por su sort_order:
+      sorter = ->(x,y) { x[:sort_order] <=> y[:sort_order] }
+
+      blueprint_ast[:resourceGroups].each do |resource_group_ast|
+        resource_group_ast[:resources].each do |resource_ast|
+          resource_ast[:actions].each do |action_ast|
+            action_ast[:examples].sort!(&sorter)
+          end
+          resource_ast[:actions].sort!(&sorter)
+        end
+        resource_group_ast[:resources].sort!(&sorter)
+      end
+      blueprint_ast[:resourceGroups].sort!(&sorter)
+      
+      # Generar el directorio a partir del nombre del api:
+      api_docs_path = File.join(Apitecto.output_dir, api_name)
+      Dir.mkdir(api_docs_path) unless Dir.exists?(api_docs_path)
+
+      # Generar el archivo de API Blueprint:
+      api_blueprint_path = File.join(api_docs_path, "api_blueprint.md")
+      
+      blueprint = MatterCompiler::Blueprint.new(blueprint_ast)
+      
+      File.open(api_blueprint_path, "w") { |f| f.write blueprint.serialize }
+      
+    end
+  end
+end

data/lib/apitecto/version.rb

@@ -0,0 +1,3 @@
+module Apitecto
+  VERSION = "0.0.1"
+end

data/spec/apitecto_spec.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+
+describe Apitecto do
+  it 'has a version number' do
+    expect(Apitecto::VERSION).not_to be nil
+  end
+
+  it 'does something useful' do
+    expect(false).to eq(true)
+  end
+end

data/spec/spec_helper.rb

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

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: apitecto
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Roberto Quintanilla
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-09-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: matter_compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A ruby library for generating REST Api documentation using API Blueprint
+email:
+- roberto.quintanilla@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- apitecto.gemspec
+- lib/apitecto.rb
+- lib/apitecto/version.rb
+- spec/apitecto_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+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.0.14
+signing_key: 
+specification_version: 4
+summary: A ruby library for generating REST Api documentation using API Blueprint
+test_files:
+- spec/apitecto_spec.rb
+- spec/spec_helper.rb