api_docs 0.0.4 → 1.0.0

data/Gemfile

@@ -0,0 +1,8 @@
+source 'http://rubygems.org'
+
+gem 'rails', '>=3.1.0'
+gem 'jquery-rails'
+
+group :development do
+  gem 'jeweler'
+end

data/README.md

@@ -1,166 +1,82 @@
-# API docs
-
-A tool to help you generate documentation for you API
+# API Docs [![Build Status](https://secure.travis-ci.org/twg/api_docs.png)](http://travis-ci.org/twg/api_docs)
+A tool to help you generate documentation for your API using integration tests in Rails 3.
 
 
 ## Installation
+Add gem definition to your Gemfile and `bundle install`:
 
-Add gem definition to your Gemfile:
-    
-``` ruby
+```
 gem 'api_docs'
 ```
-    
-Bundle it:
-    
-    bundle install
 
-Add [Twitter bootstrap](http://twitter.github.com/bootstrap) and [Google code pretifyer](http://google-code-prettify.googlecode.com/svn/trunk/README.html) to you CSS manifest file
+To access generated docs mount it to a path in your `routes.rb` like this:
 
-``` js
-//= require bootstrap
-//= require prettify
+``` ruby
+mount ApiDocs::Engine => '/api-docs'
 ```
 
-Here's what you Javascript manifest file should look like
+You may also want to add js/css to your asset pipeline manifests:
 
-``` js
-//= require jquery
-//= require jquery_ujs
-//= require bootstrap
-//= require prettify
-//= require api_docs
 ```
+require api_docs
+```
+
+Documents view is made to work with [Twitter Bootstrap](http://twitter.github.com/bootstrap) css and js libraries.
 
-Add your API documentation files to the /doc/api folder and in your view do:
+## Generating Api Docs
+Documentation is automatically generated into yaml files from tests you create to test your api controllers. To start, let's create integration test by running `rails g integration_test users`. This will create a file for you to work with. Here's a simple test we can do:
 
 ``` ruby
-= render_api_docs %w{login users overview}
+class UsersTest < ActionDispatch::IntegrationTest
+  def test_get_user
+    user = users(:default)
+    api_call(:get, '/users/:id', :id => user.to_param) do |doc|
+      assert_response :success
+      assert_equal ({
+        'id'    => user.id,
+        'name'  => user.name
+      }), JSON.parse(response.body)
+    end
+  end
+
+  def test_get_user_failure
+    api_call(:get, '/users/:id', :id => 'invalid') do |doc|
+      doc.description = 'When bad user id is passed'
+      assert_response :not_found
+      assert_equal ({
+        'message' => 'User not found'
+      }), JSON.parse(response.body)
+    end
+  end
+end
 ```
 
-## The API documentation files
-  
-Here's a sample API for users
-
-``` yaml
-'List':
-  url: '/users'
-  method: GET
-  description: Returns a list of users
-  params:
-    api_key:
-    keyword: "a string of one or more words used to filter the users by first_name, last_name and email (optional)"
-  success:
-    response: 'HTTP/1.1 200 OK'
-    data: |
-      {
-        "users": [
-          {
-            "id": 27,
-            "first_name": "John",
-            "last_name": "Smith",
-            "created_at": "2011-06-13T00:28:36-04:00",
-            "updated_at": "2012-04-26T20:21:43-04:00"
-          },
-          {
-            "id": 3,
-            "first_name": "Anna",
-            "last_name": "Brown",
-            "created_at": "2011-06-13T00:28:36-04:00",
-            "updated_at": "2012-04-26T20:21:43-04:00"
-          },
-          ...
-        ]
-      }
-  fail:
-    response: 'HTTP/1.1 422 Unprocessable Entity'
-    data: |
-      {
-        "message": "Failed to create User",
-        "errors" : {
-          "email": "Email is invalid",
-          ...
-        }
-      }
-
-  curl: curl -i :api_url/users?api_key=7gR9hZt3DBqcuzi2mZKN
-
-# ------------------------------
-
-'Show':
-  url: '/users/:id'
-  method: GET
-  description: |
-    Returns profile details for a specified user.
-    <span class=label>NOTE</span> If showing details of another user the email is ommited
-  params:
-    api_key:
-    id: the id of a user
-  success:
-    response: 'HTTP/1.1 200 OK'
-    data: |
-      {
-        "user": {
-          "id": 917,
-          "api_key": "7gR9hZt3DBqcuzi2mZKN",
-          "email": "john_smith@gmail.com",
-          "first_name": "John",
-          "last_name": "Smith",
-          "created_at": "2011-06-13T00:28:36-04:00",
-          "updated_at": "2012-04-26T20:21:43-04:00"
-        }
-      }
-  fail:
-    response: 'HTTP/1.1 404 Not Found'
-    data: |
-      {
-        "message": "User not found"
-      }
-  curl: curl -i :api_url/users/197?api_key=2a10K5ipBd2qapJsPvCso90kMO
-
-# ------------------------------
-
-'Create':
-  url: '/users'
-  method: POST
-  description: Create a user
-  params:
-    user[first_name]:
-    user[last_name]:
-    user[email]:
-    user[password]:
-  success:
-    response: 'HTTP/1.1 201 Created'
-    data: |
-      {
-        "user": {
-          "id": 917,
-          "api_key": "7gR9hZt3DBqcuzi2mZKN",
-          "email": "john_smith@gmail.com",
-          "first_name": "John",
-          "last_name": "Smith",
-          "created_at": "2011-06-13T00:28:36-04:00",
-          "updated_at": "2012-04-26T20:21:43-04:00"
-        }
-      }
-  fail:
-    response: 'HTTP/1.1 422 Unprocessable Entity'
-    data: |
-      {
-        "message": "Failed to create User",
-        "errors" : {
-          "email": "Email is invalid",
-          ...
-        }
-      }
-  curl: |
-    curl -i :api_url/v1/users \
-      -d "user[first_name]=John" \
-      -d "user[last_name]=Smith" \
-      -d "user[email]=john_smith@twg.ca" \
-      -d "user[password]=passpass"
+Assuming that tests pass their details are doing to be recorded into `docs/api/users.yml` and they will look like this:
+
+``` yml
+show:
+  1YGvw8qQDy0Te4oEAxFdTEiS3eQ=:
+    method: GET
+    path: /users/:id
+    params:
+      id: 12345
+    status: 200
+    body:
+      id: 12345
+      name: John Doe
+  YaEdGJRDZy0nsljmpJmOtcLxdUg=:
+    description: When bad user id is passed
+    method: GET
+    path: /users/:id
+    params:
+      id: invalid
+    status: 404
+    body:
+      message: User not found
 ```
 
+## Usage
+Just navigate to the path you mounted *api_docs* to. Perhaps `http://yourapp/api-docs`.
 
 ## Configuration
 
@@ -168,12 +84,15 @@ You can change the default configuration of this gem by adding the following cod
 
 ``` ruby
 ApiDocs.configure do |config|
-  config.yaml_docs_folder = '/some/other/folder ' # the default folder is /doc/api
+  # folder path where api docs are saved to
+  config.docs_path = Rails.root.join('doc/api')
+  
+  # controller that ApiDocs controller inherits from.
+  # Useful for hiding it behind admin controller.
+  config.base_controller = 'ApplicationController'
 end
 ```
 
-
 ---
 
-Copyright 2012 Jack Neto, [The Working Group, Inc](http://www.theworkinggroup.ca)
-
+Copyright 2012 Oleg Khabarov, Jack Neto, [The Working Group, Inc](http://twg.ca)

data/Rakefile

@@ -1,16 +1,31 @@
-require 'rubygems'
-require 'rake'
-require 'jeweler'
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name        = 'api_docs'
+    gem.homepage    = 'http://github.com/twg/api_docs'
+    gem.license     = 'MIT'
+    gem.summary     = 'Generate API documentation using integration tests in Ruby on Rails 3'
+    gem.description = 'Generate API documentation using integration tests in Ruby on Rails 3'
+    gem.email       = 'jack@twg.ca'
+    gem.authors     = ['Oleg Khabarov', 'Jack Neto', 'The Working Group Inc.']
+  end
+  Jeweler::RubygemsDotOrgTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
 
-Jeweler::Tasks.new do |gem|
-  gem.name = "api_docs"
-  gem.homepage = "http://github.com/twg/api_docs"
-  gem.license = "MIT"
-  gem.summary = "A tool to help you generate documentation for you API"
-  gem.description = ''
-  gem.email = "jack@twg.ca"
-  gem.authors = ["Jack Neto", 'The Working Group Inc.']
-  gem.add_dependency('rails', '>=3.1.0')
-  gem.add_dependency('bootstrap_builder', '>=0.2.6')
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
 end
-Jeweler::RubygemsDotOrgTasks.new
+task :default => :test

data/VERSION

@@ -1 +1 @@
-0.0.4
+1.0.0

data/api_docs.gemspec

@@ -4,58 +4,99 @@
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
-  s.name = %q{api_docs}
-  s.version = "0.0.4"
+  s.name = "api_docs"
+  s.version = "1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Jack Neto", "The Working Group Inc."]
-  s.date = %q{2012-05-03}
-  s.description = %q{}
-  s.email = %q{jack@twg.ca}
+  s.authors = ["Oleg Khabarov", "Jack Neto", "The Working Group Inc."]
+  s.date = "2012-09-11"
+  s.description = "Generate API documentation using integration tests in Ruby on Rails 3"
+  s.email = "jack@twg.ca"
   s.extra_rdoc_files = [
-    "LICENSE.txt",
+    "LICENSE",
     "README.md"
   ]
   s.files = [
-    "LICENSE.txt",
+    "Gemfile",
+    "LICENSE",
     "README.md",
     "Rakefile",
     "VERSION",
     "api_docs.gemspec",
-    "app/assets/javascripts/api_docs.js.coffee",
-    "app/assets/javascripts/prettify.js",
-    "app/assets/stylesheets/prettify.css",
-    "app/views/api_docs/_api_docs.html.haml",
-    "app/views/api_docs/_curl.html.haml",
-    "app/views/api_docs/_form.html.haml",
-    "app/views/api_docs/_panel.html.haml",
-    "app/views/api_docs/_params.html.haml",
-    "app/views/api_docs/_response.html.haml",
+    "app/assets/javascripts/api_docs.js",
+    "app/assets/stylesheets/api_docs.css",
+    "app/controllers/api_docs/docs_controller.rb",
+    "app/views/api_docs/docs/_action.html.erb",
+    "app/views/api_docs/docs/_request_params.html.erb",
+    "app/views/api_docs/docs/index.html.erb",
+    "config/routes.rb",
     "lib/api_docs.rb",
     "lib/api_docs/configuration.rb",
     "lib/api_docs/engine.rb",
-    "lib/api_docs/railtie.rb"
+    "lib/api_docs/test_helper.rb",
+    "script/rails",
+    "test/api_docs_test.rb",
+    "test/docs_controller_test.rb",
+    "test/dummy/README.rdoc",
+    "test/dummy/Rakefile",
+    "test/dummy/app/assets/images/glyphicons-halflings-white.png",
+    "test/dummy/app/assets/images/glyphicons-halflings.png",
+    "test/dummy/app/assets/javascripts/application.js",
+    "test/dummy/app/assets/javascripts/bootstrap.min.js",
+    "test/dummy/app/assets/stylesheets/application.css",
+    "test/dummy/app/assets/stylesheets/bootstrap.min.css",
+    "test/dummy/app/controllers/application_controller.rb",
+    "test/dummy/app/helpers/application_helper.rb",
+    "test/dummy/app/mailers/.gitkeep",
+    "test/dummy/app/models/.gitkeep",
+    "test/dummy/app/views/layouts/application.html.erb",
+    "test/dummy/config.ru",
+    "test/dummy/config/application.rb",
+    "test/dummy/config/boot.rb",
+    "test/dummy/config/environment.rb",
+    "test/dummy/config/environments/development.rb",
+    "test/dummy/config/environments/production.rb",
+    "test/dummy/config/environments/test.rb",
+    "test/dummy/config/initializers/backtrace_silencers.rb",
+    "test/dummy/config/initializers/inflections.rb",
+    "test/dummy/config/initializers/mime_types.rb",
+    "test/dummy/config/initializers/secret_token.rb",
+    "test/dummy/config/initializers/session_store.rb",
+    "test/dummy/config/initializers/wrap_parameters.rb",
+    "test/dummy/config/locales/en.yml",
+    "test/dummy/config/routes.rb",
+    "test/dummy/lib/assets/.gitkeep",
+    "test/dummy/log/.gitkeep",
+    "test/dummy/public/404.html",
+    "test/dummy/public/422.html",
+    "test/dummy/public/500.html",
+    "test/dummy/public/favicon.ico",
+    "test/dummy/script/rails",
+    "test/test_helper.rb",
+    "test/test_helper_test.rb"
   ]
-  s.homepage = %q{http://github.com/twg/api_docs}
+  s.homepage = "http://github.com/twg/api_docs"
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
-  s.summary = %q{A tool to help you generate documentation for you API}
+  s.rubygems_version = "1.8.23"
+  s.summary = "Generate API documentation using integration tests in Ruby on Rails 3"
 
   if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<rails>, [">= 3.1.0"])
-      s.add_runtime_dependency(%q<bootstrap_builder>, [">= 0.2.6"])
+      s.add_runtime_dependency(%q<jquery-rails>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
     else
       s.add_dependency(%q<rails>, [">= 3.1.0"])
-      s.add_dependency(%q<bootstrap_builder>, [">= 0.2.6"])
+      s.add_dependency(%q<jquery-rails>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
     end
   else
     s.add_dependency(%q<rails>, [">= 3.1.0"])
-    s.add_dependency(%q<bootstrap_builder>, [">= 0.2.6"])
+    s.add_dependency(%q<jquery-rails>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
   end
 end
 

data/app/assets/javascripts/api_docs.js

@@ -0,0 +1,11 @@
+// This is a manifest file that'll be compiled into including all the files listed below.
+// Add new JavaScript/Coffee code in separate files in this directory and they'll automatically
+// be included in the compiled file accessible from http://example.com/assets/application.js
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_self
+
+

data/app/assets/stylesheets/api_docs.css

@@ -0,0 +1,62 @@
+/*
+ * This is a manifest file that'll automatically include all the stylesheets available in this directory
+ * and any sub-directories. You're free to add application-wide styles to this file and they'll appear at
+ * the top of the compiled file, but it's generally better to create a new file per style scope.
+ *= require_self
+*/
+
+ul#api-doc-nav {
+  box-shadow: 0px 1px 4px rgba(0, 0, 0, 0.067);
+  border-radius: 6px;
+}
+ul#api-doc-nav li {
+  font: 14px/20px 'Helvetica Neue', Helvetica, Arial, sans-serif;
+}
+ul#api-doc-nav li.nav-header {
+  background-color: #e5e5e5;
+  margin-top: 0px;
+  padding-top: 5px;
+}
+ul#api-doc-nav a {
+  border: 1px solid #e5e5e5;
+  padding: 8px 14px;
+  margin-top: -1px;
+  text-align: right;
+}
+ul#api-doc-nav > li:first-child {
+  border-radius: 6px 6px 0px 0px;
+}
+ul#api-doc-nav > li:last-child > a {
+  border-radius: 0px 0px 6px 6px;
+}
+
+table#api-doc-table th {
+  text-align: right;
+  min-width: 100px;
+}
+table#api-doc-table  td {
+ width: 100%;
+}
+table#api-doc-table  tr.info th {
+  background-color: #D9EDF7 !important;
+}
+table#api-doc-table  tr.info td {
+  background-color: #F0F8FC !important;
+}
+table#api-doc-table  tr.info td code {
+  color: #3A87AD !important;
+}
+table#api-doc-table  td pre {
+  margin-bottom: 0px;
+}
+table#api-doc-table  td table {
+  width: auto;
+}
+table#api-doc-table  td table th {
+  width: auto;
+  min-width: 0px;
+  border-left: 0px;
+}
+table#api-doc-table  td table td {
+  width: auto;
+}

data/app/controllers/api_docs/docs_controller.rb

@@ -0,0 +1,8 @@
+class ApiDocs::DocsController < ApiDocs.config.base_controller.to_s.constantize
+  def index
+    @api_controllers = { }
+    Dir.glob(ApiDocs.config.docs_path.join('*.yml')).each do |file_path|
+      @api_controllers[File.basename(file_path, '.yml')] = YAML.load_file(file_path)
+    end
+  end
+end

data/app/views/api_docs/docs/_action.html.erb

@@ -0,0 +1,41 @@
+<table class='table table-bordered table-condensed' id='api-doc-table'>
+  
+  <tr class='info'>
+    <th>Request</th>
+    <td>
+      <span class='label label-info'><%= action['method']%></span>
+      <code><%= action['path']%></code>
+    </td>
+  </tr>
+  
+  <% if action['description'].present? %>
+    <tr>
+      <th>Description</th>
+      <td><%= action['description']%></td>
+    </tr>
+  <% end %>
+  
+  <% if action['params'].is_a?(Hash) %>
+    <tr>
+      <th>Parameters</th>
+      <td>
+        <%= render :partial => 'request_params', :object => action['params'] %>
+      </td>
+    </tr>
+  <% end %>
+  
+  <tr class='info'>
+    <th>Response</th>
+    <td>
+      <span class='label <%= action['status'].to_s[0] == '4' ? 'label-important' : 'label-success' %>'>
+        <%= action['status'] %>
+      </span>
+    </td>
+  </tr>
+  
+  <tr>
+    <th>Body</th>
+    <td><pre><%= JSON.pretty_generate(action['body']) %></pre></td>
+  </tr>
+  
+</table>

data/app/views/api_docs/docs/_request_params.html.erb

@@ -0,0 +1,16 @@
+<table>
+  <% request_params.each do |key, value| %>
+    <tr>
+      <th><%= key %></th>
+      <td>
+        <%= 
+          if value.is_a?(Hash)
+            render :partial => 'request_params', :object => value
+          else
+            value
+          end
+        %>
+      </td>
+    </tr>
+  <% end %>
+</table>

data/app/views/api_docs/docs/index.html.erb

@@ -0,0 +1,32 @@
+<div class='row'>
+  <div class='span3'>
+    <ul class='nav nav-list' id='api-doc-nav'>
+      <% @api_controllers.each_with_index do |(controller, actions), ci| %>
+        <li class='nav-header'>
+          <%= controller.gsub(/\W/, '_').humanize.titleize %>
+        </li>
+        <% actions.each_with_index do |(action, data), ai| %>
+          <li class='<%= ci == 0 && ai == 0 ? 'active' : '' %>'>
+            <% tab_id = "#{controller.gsub(/\W/, '_')}_#{action}" %>
+            <%= link_to action.humanize.titleize, "##{tab_id}", :data => {:toggle => 'tab'} %>
+          </li>
+        <% end %>
+      <% end %>
+    </ul>
+  </div>
+  
+  <div class="span9">
+    <div class='tab-content'>
+      <% @api_controllers.each_with_index do |(controller, actions), ci| %>
+        <% actions.each_with_index do |(action, data), ai| %>
+          <% tab_id = "#{controller.gsub(/\W/, '_')}_#{action}" %>
+          <div class='tab-pane <%= ci == 0 && ai == 0 ? 'active' : '' %>' id='<%= tab_id %>'>
+            <% data.each do |key, data| %>
+              <%= render :partial => 'action', :object => data %>
+            <% end %>
+          </div>
+        <% end %>
+      <% end %>
+    </div>
+  </div>
+</div>

data/config/routes.rb

@@ -0,0 +1,3 @@
+ApiDocs::Engine.routes.draw do
+  root :to => 'docs#index'
+end

data/lib/api_docs/configuration.rb

@@ -1,14 +1,19 @@
-module ApiDocs
-  class Configuration
-
-    # Where to find the folder with the yaml docs
-    attr_accessor :yaml_docs_folder, :api_url
-        
-    # Configuration defaults
-    def initialize
-      @yaml_docs_folder = '/doc'
-      @api_url = 'http://localhost:3000'
-    end
+class ApiDocs::Configuration
+  
+  # Where to find the folder with documentation files
+  attr_accessor :docs_path
+  
+  # Controller that ApiDocs::DocsController inherits from
+  attr_accessor :base_controller
+  
+  # Array of ignored attributes. Attributes that don't really change
+  # the content like timestamps.
+  attr_accessor :ignored_attributes
     
+  # Configuration defaults
+  def initialize
+    @docs_path          = Rails.root.join('doc/api')
+    @base_controller    = 'ApplicationController'
+    @ignored_attributes = %w(created_at updated_at)
   end
 end

data/lib/api_docs/engine.rb

@@ -1,8 +1,5 @@
-require "api_docs"
-require "rails"
-
 module ApiDocs
-  class Engine < Rails::Engine
-
+  class Engine < ::Rails::Engine
+    isolate_namespace ApiDocs
   end
-end
+end