grape_doc 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rvmrc

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+
+# This is an RVM Project .rvmrc file, used to automatically load the ruby
+# development environment upon cd'ing into the directory
+
+# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional,
+# Only full ruby name is supported here, for short names use:
+#     echo "rvm use 1.9.2" > .rvmrc
+environment_id="ruby-1.9.2-p320@grape_doc"
+
+# Uncomment the following lines if you want to verify rvm version per project
+# rvmrc_rvm_version="1.13.6 (stable)" # 1.10.1 seams as a safe start
+# eval "$(echo ${rvm_version}.${rvmrc_rvm_version} | awk -F. '{print "[[ "$1*65536+$2*256+$3" -ge "$4*65536+$5*256+$6" ]]"}' )" || {
+#   echo "This .rvmrc file requires at least RVM ${rvmrc_rvm_version}, aborting loading."
+#   return 1
+# }
+
+# First we attempt to load the desired environment directly from the environment
+# file. This is very fast and efficient compared to running through the entire
+# CLI and selector. If you want feedback on which environment was used then
+# insert the word 'use' after --create as this triggers verbose mode.
+if [[ -d "${rvm_path:-$HOME/.rvm}/environments"
+  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]]
+then
+  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
+  [[ -s "${rvm_path:-$HOME/.rvm}/hooks/after_use" ]] &&
+    \. "${rvm_path:-$HOME/.rvm}/hooks/after_use" || true
+else
+  # If the environment file has not yet been created, use the RVM CLI to select.
+  rvm --create  "$environment_id" || {
+    echo "Failed to create RVM environment '${environment_id}'."
+    return 1
+  }
+fi
+
+# If you use bundler, this might be useful to you:
+# if [[ -s Gemfile ]] && {
+#   ! builtin command -v bundle >/dev/null ||
+#   builtin command -v bundle | GREP_OPTIONS= \grep $rvm_path/bin/bundle >/dev/null
+# }
+# then
+#   printf "%b" "The rubygem 'bundler' is not installed. Installing it now.\n"
+#   gem install bundler
+# fi
+# if [[ -s Gemfile ]] && builtin command -v bundle >/dev/null
+# then
+#   bundle install | GREP_OPTIONS= \grep -vE '^Using|Your bundle is complete'
+# fi

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# 0.0.1
+
+ - markdown formatter
+ - generate single doc file doc/api.md
+ - rails only
+ - generate only parameters documentation
+

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in grape_doc.gemspec
+gemspec
+
+gem 'rspec'
+gem 'grape'
+gem 'json'
+gem 'rake'

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Alex Denisov
+
+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,83 @@
+# GrapeDoc
+
+This gem generate API documentation from Grape API.
+
+## Installation
+
+Add this line to your application's Gemfile under development group
+
+    gem 'grape_doc'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install grape_doc
+
+## Usage
+
+To generate API documentation you should cd to rails app directory
+
+    $ cd rails_app
+
+Then run 
+
+    $ grape_doc
+
+It'll generate documentation for each Grape::API subclass and place it into **doc** directory. Each API subclass were placed as separated file.   
+
+You can pass a doc formatter as parameter
+
+    $ grape_doc markdown
+
+_At this time it supports only MarkDown format._
+
+## API description
+
+### Parameters
+
+#### grape > 0.2.1
+
+    desc "Returns a tweet."
+    params do
+      requires :id, 
+               :type => Integer, 
+               :desc => "Tweet id."
+    end
+    get '/show/:id' do
+      Tweet.find(params[:id])
+    end
+
+#### grape <= 0.2.1
+
+    desc "Returns a tweet.",
+    :params => {
+      :id => {
+        :desc => "Tweet id.",
+        :type => Integer,
+        :requires => true
+      }
+    }
+    get '/show/:id' do
+      Tweet.find(params[:id])
+    end
+
+## TODO
+
+ - generate plain response
+ - generate response from Grape::Entity
+ - generate response from Grape::Entity with nested entities
+ - other output formats
+ - write docs into separated files
+ - add code documentation
+ - and more others features
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new('spec')
+
+task :default => 'spec'

data/bin/grape_doc

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'grape_doc'
+GrapeDoc.generate_doc
+

data/grape_doc.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/grape_doc/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Alex Denisov"]
+  gem.email         = ["1101.debian@gmail.com"]
+  gem.description   = %q{Documentation generator for Grape API}
+  gem.summary       = %q{Documentation generator for Grape API}
+  gem.homepage      = "https://github.com/AlexDenisov/grape_doc"
+  gem.files         = `git ls-files`.split($\)
+  gem.executables << "grape_doc"
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "grape_doc"
+  gem.require_paths = ["lib"]
+  gem.version       = GrapeDoc::VERSION
+  gem.add_runtime_dependency 'grape', '~> 0.2', '>= 0.2.1'
+  gem.add_runtime_dependency 'json', '~> 1.7', '>= 1.7.4'
+  gem.add_development_dependency 'rspec', '~> 2.11'
+end

data/lib/core_ext/object.rb

@@ -0,0 +1,18 @@
+module Subclasses
+  def subclasses(direct = false)
+    classes = []
+    if direct
+      ObjectSpace.each_object(Class) do |c|
+        next unless c.superclass == self
+        classes << c
+      end
+    else
+      ObjectSpace.each_object(Class) do |c|
+        next unless c.ancestors.include?(self) and (c != self)
+        classes << c
+      end
+    end
+    classes
+  end
+end
+Object.send(:include, Subclasses)

data/lib/grape_doc/api_document.rb

@@ -0,0 +1,33 @@
+module GrapeDoc
+  class APIDocument
+    attr_accessor :resource_name, 
+                  :path, 
+                  :description, 
+                  :params,
+                  :response, 
+                  :http_method, 
+                  :empty
+    def initialize(resource = nil, route = nil)
+      return if route.nil?
+      if route.route_path == "/:version/(.:format)"
+        self.empty = true
+        return
+      end
+      self.path = route.route_path.gsub('(.:format)','')
+      self.resource_name = resource
+      self.http_method = route.route_method
+      self.description = route.route_description
+      self.params = APIParameter.initialize_parameters route.route_params
+      self.response = nil_or_empty route.route_response
+    end
+
+    private 
+    def nil_or_empty(hash)
+      if hash
+        return hash.empty? ? nil : hash
+      end
+      hash
+    end
+  end
+end
+

data/lib/grape_doc/api_parameter.rb

@@ -0,0 +1,29 @@
+module GrapeDoc
+  class APIParameter
+    attr_accessor :field, 
+                  :description, 
+                  :sample_value, 
+                  :field_type,
+                  :required
+    def initialize(parameter_name = nil, 
+                   parameter_hash = nil)
+      return if parameter_name.nil? or 
+                parameter_hash.nil? or
+                parameter_hash.empty? or
+                parameter_name.empty?
+      self.field = parameter_name.to_s
+      self.required = parameter_hash[:requires] || 
+                      parameter_hash[:required]
+      self.description =  parameter_hash[:desc] ||
+                          parameter_hash[:description]
+    end
+    def self.initialize_parameters(params_hash)
+      params = params_hash.map do |name, hash|
+        APIParameter.new(name, hash)
+      end
+      return nil if params.empty?
+      params
+    end
+  end
+end
+

data/lib/grape_doc/api_parser.rb

@@ -0,0 +1,19 @@
+module GrapeDoc
+  class APIParser
+    def self.parse(klass)
+      return nil if klass.routes.count.zero?
+      documents = klass.routes.map do |route|
+        resource = klass.to_s.split("::").last
+        document = APIDocument.new(resource, route)
+        if document.empty
+          nil
+        else
+          document
+        end
+      end.compact.sort_by{ |doc| doc.resource_name }
+    end
+    def parse(klass)
+      self.class.parse klass
+    end
+  end
+end

data/lib/grape_doc/api_resource.rb

@@ -0,0 +1,11 @@
+module GrapeDoc
+  class APIResource
+    attr_accessor :documents
+    attr_accessor :resource_name
+    def initialize(klass)
+      self.resource_name = klass.to_s.split("::").last
+      self.documents = APIParser.parse klass
+    end
+  end
+end
+

data/lib/grape_doc/doc_generator.rb

@@ -0,0 +1,32 @@
+module GrapeDoc 
+  class DOCGenerator 
+    attr_accessor :resources, 
+                  :formatter, 
+                  :single_file
+    def initialize
+      self.resources = Grape::API.subclasses.map do |klass|
+        resource = APIResource.new(klass)
+        if resource.documents.nil? or resource.documents.count.zero?
+          nil
+        else
+          resource
+        end
+      end.compact.sort_by{ |res| res.resource_name }
+    end
+
+    def init_formatter
+      return GrapeDoc::MarkdownFormatter.new self.formatter.nil?
+      
+    end
+
+    def generate
+      doc_formatter = init_formatter
+      generated_resources = self.resources.map do | resource |
+        doc_formatter.generate_resource_doc resource
+      end.join
+      output = File.open("#{Dir.pwd}/doc/api.md", "w")
+      output << generated_resources
+    end
+  end
+end
+

data/lib/grape_doc/formatters/markdown_formatter.rb

@@ -0,0 +1,28 @@
+module GrapeDoc
+  class MarkdownFormatter 
+    def generate_resource_doc(resource)
+      title = "### #{resource.resource_name}\n"
+      
+      documents = resource.documents.map do |document|
+        path = "#### #{document.http_method} #{document.path}\n\n"
+        description = "#{document.description}\n\n"
+        
+        parameters = document.params.map do |parameter| 
+          next if parameter.field.nil? or parameter.field.empty?
+          param = " - #{parameter.field}"
+          param += " (#{parameter.field_type})" if parameter.field_type
+          param += " (required)" if parameter.required
+          param += " : #{parameter.description}\n\n"
+        end.join if document.params
+        
+        route = "#{path} #{description}"
+        route += "**Parameters:** \n\n\n#{parameters}" if parameters
+        route += "\n\n"
+
+      end.join
+      return "" if documents.nil? or documents.empty?
+      "#{title}\n\n\n#{documents}\n"
+    end
+  end
+end
+

data/lib/grape_doc/version.rb

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

data/lib/grape_doc.rb

@@ -0,0 +1,21 @@
+require 'core_ext/object'
+require 'grape_doc/version'
+require 'grape_doc/api_document'
+require 'grape_doc/api_parser'
+require 'grape_doc/api_parameter'
+require 'grape_doc/api_resource'
+require 'grape_doc/doc_generator'
+require 'grape_doc/formatters/markdown_formatter'
+
+begin
+require File.expand_path(Dir.pwd + "/config/environment")
+rescue LoadError => ex
+  puts "#{ex}"
+end
+
+module GrapeDoc
+  def self.generate_doc
+    generator = DOCGenerator.new
+    generator.generate
+  end
+end

data/spec/api_document_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+
+describe "GrapeDoc::APIDocument" do
+  describe "should respond to" do
+    let(:api_document) {
+      GrapeDoc::APIDocument.new 
+    }
+    it "resource" do
+      api_document.respond_to?(:resource_name).should be_true
+    end
+    it "path" do
+      api_document.respond_to?(:path).should be_true
+    end
+    it "description" do
+      api_document.respond_to?(:description).should be_true
+    end
+    it "params" do
+      api_document.respond_to?(:params).should be_true
+    end
+    it "response" do
+      api_document.respond_to?(:response).should be_true
+    end
+    it "http_method" do
+      api_document.respond_to?(:http_method).should be_true
+    end
+  end
+end
+

data/spec/api_parameter_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+require 'test_classes/projects'
+
+include GrapeDoc
+
+describe GrapeDoc::APIParameter do
+  let(:parser) { APIParser.new }
+  let(:parameter) { APIParameter.new }
+
+  describe "should respond to" do
+    it "field" do
+      parameter.respond_to?(:field).should be_true
+    end
+    it "description" do
+      parameter.respond_to?(:description).should be_true
+    end
+    it "sample_value" do
+      parameter.respond_to?(:sample_value).should be_true
+    end
+    it "field_type" do
+      parameter.respond_to?(:field_type).should be_true
+    end
+  end
+
+  describe "initialize within different data" do
+    it "parse PUT project" do
+      document = parser.parse(Projects)[2]
+      params = document.params
+      params.each do |p|
+        p.kind_of?(APIParameter).should be_true
+      end
+    end
+    it "parse PUT project with parameters" do
+      document = parser.parse(Projects)[2]
+      param = document.params.first
+      param.field.should == "project_id"
+      param.description.should == "Project ID"
+      param.required.should be_true
+    end
+  end
+end
+

data/spec/api_parser_spec.rb

@@ -0,0 +1,78 @@
+require 'spec_helper'
+
+require 'test_classes/projects'
+require 'test_classes/users'
+include GrapeDoc
+
+describe GrapeDoc::APIParser do
+  let(:parser) { APIParser.new }
+  describe "parse empty child class" do
+    it "should return nil" do
+      parser.parse(Users).should be_nil
+    end
+  end
+  describe "parse non-empty child class" do
+    it "should_not return nil" do
+      parser.parse(Projects).should_not be_nil
+    end
+    it "should return two documents" do
+      parser.parse(Projects).count.should == 4
+    end
+    it "should return array of APIDocument objects" do
+      parser.parse(Projects).each do |document|
+        document.kind_of?(APIDocument).should be_true
+      end
+    end
+    it "should parse GET route without meta info" do
+      document = parser.parse(Projects).first
+      document.resource_name.should == "Projects"
+      document.path.should == "/projects"
+      document.http_method.should == "GET"
+      document.description.should be_nil
+      document.params.should be_nil
+      document.response.should be_nil
+    end
+    it "should parse POST route within meta info" do
+      document = parser.parse(Projects)[1]
+      document.resource_name.should == "Projects"
+      document.path.should == "/projects"
+      document.http_method.should == "POST"
+      document.description.should == "Create Project"
+      document.params.should be_nil
+      document.response.should be_nil
+    end
+    it "should parse PUT route within meta info" do
+      params = { 
+        :project_id => { 
+          :desc => "Project ID",
+          :required => true
+        }
+      }
+      document = parser.parse(Projects)[2]
+      document.resource_name.should == "Projects"
+      document.path.should == "/projects"
+      document.http_method.should == "PUT"
+      document.description.should == "Update Project"
+      document.response.should be_nil
+    end
+    it "should parse DELETE route within meta info" do
+      params = { 
+        :project_id => { 
+          :desc => "Project ID",
+          :required => true
+        }
+      }
+      response = {
+        :status => true
+      }
+      document = parser.parse(Projects)[3]
+      document.resource_name.should == "Projects"
+      document.path.should == "/projects"
+      document.http_method.should == "DELETE"
+      document.description.should == "Delete Project"
+#      document.params.should == params
+      document.response.should == response
+    end
+  end
+end
+

data/spec/api_resource_spec.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+require 'test_classes/projects'
+
+describe GrapeDoc::APIResource do
+  it "should have 4 documents" do
+    resource = APIResource.new(Projects)
+    resource.documents.count.should == 4
+  end
+end
+

data/spec/api_response.rb

@@ -0,0 +1,9 @@
+require 'spec_helper'
+require 'test_classes/projects'
+
+describe "APIResponse" do
+  it "should parse response" do
+
+  end
+end
+

data/spec/doc_generator_spec.rb

@@ -0,0 +1,8 @@
+require 'spec_helper'
+
+describe GrapeDoc::DOCGenerator do
+  it "resources" do
+    generator = DOCGenerator.new
+    generator.resources.count.should == 1
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'grape_doc'
+
+begin
+  require 'grape'
+rescue Gem::LoadError
+  puts "Cannot load 'grape' gem"
+end
+
+RSpec.configure do |config|
+  config.formatter = 'documentation'
+end

data/spec/test_classes/api.rb

@@ -0,0 +1,9 @@
+require 'test_classes/users'
+require 'test_classes/projects'
+module GrapeDoc
+  class API < Grape::API
+    mount Projects
+    mount Users
+  end
+end
+

data/spec/test_classes/projects.rb

@@ -0,0 +1,42 @@
+module GrapeDoc
+  class Projects < Grape::API
+    resource :projects do
+      get do
+
+      end
+
+      desc "Create Project"
+      post do
+
+      end
+
+      desc "Update Project", {
+        :params => {
+          :project_id => { 
+            :desc => "Project ID",
+            :required => true
+          }
+        }
+      }
+      put do
+
+      end
+
+      desc "Delete Project", {
+        :params => {
+          :project_id => { 
+            :desc => "Project ID",
+            :required => true
+          }
+        }, 
+        :response => {
+          :status => true
+        }
+      }
+      delete do
+
+      end
+    end
+  end
+end
+

data/spec/test_classes/users.rb

@@ -0,0 +1,8 @@
+module GrapeDoc
+  class Users < Grape::API
+    resource :users do
+     
+    end
+  end
+end
+

metadata

@@ -0,0 +1,144 @@
+--- !ruby/object:Gem::Specification
+name: grape_doc
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Alex Denisov
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: grape
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.2.1
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.7.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.7'
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.7.4
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.11'
+description: Documentation generator for Grape API
+email:
+- 1101.debian@gmail.com
+executables:
+- grape_doc
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rvmrc
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/grape_doc
+- grape_doc.gemspec
+- lib/core_ext/object.rb
+- lib/grape_doc.rb
+- lib/grape_doc/api_document.rb
+- lib/grape_doc/api_parameter.rb
+- lib/grape_doc/api_parser.rb
+- lib/grape_doc/api_resource.rb
+- lib/grape_doc/doc_generator.rb
+- lib/grape_doc/formatters/markdown_formatter.rb
+- lib/grape_doc/version.rb
+- spec/api_document_spec.rb
+- spec/api_parameter_spec.rb
+- spec/api_parser_spec.rb
+- spec/api_resource_spec.rb
+- spec/api_response.rb
+- spec/doc_generator_spec.rb
+- spec/spec_helper.rb
+- spec/test_classes/api.rb
+- spec/test_classes/projects.rb
+- spec/test_classes/users.rb
+homepage: https://github.com/AlexDenisov/grape_doc
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Documentation generator for Grape API
+test_files:
+- spec/api_document_spec.rb
+- spec/api_parameter_spec.rb
+- spec/api_parser_spec.rb
+- spec/api_resource_spec.rb
+- spec/api_response.rb
+- spec/doc_generator_spec.rb
+- spec/spec_helper.rb
+- spec/test_classes/api.rb
+- spec/test_classes/projects.rb
+- spec/test_classes/users.rb