apispec 0.0.3

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2011 Vincent Landgraf
+
+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 @@
+TODO

data/Rakefile

@@ -0,0 +1,9 @@
+require "rubygems"
+require "spec/rake/spectask"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_files = Dir.glob('spec/**/*_spec.rb')
+  t.spec_opts << '--diff --format d'
+  #t.rcov = true
+end
+
+task :default => :spec

data/apispec.gemspec

@@ -0,0 +1,37 @@
+$:.push('lib')
+require "apispec/version"
+
+Gem::Specification.new do |s|
+  s.name        = 'apispec'
+  s.version     = APISpec::VERSION.dup
+  s.date        = Time.now
+  s.summary     = "A ruby based http/rest documentation generator"
+  s.email       = "vilandgr+github@googlemail.com"
+  s.homepage    = "http://github.com/threez/apispec/"
+  s.authors     = ['Vincent Landgraf']
+  s.description = "A documentation generator for http/rest"
+  
+  dependencies = [
+    [:runtime,     "RedCloth", "~> 4.2.7"],
+    [:runtime,     "coderay",  "~> 0.9.7"],
+    [:development, "rspec",    "~> 2.1"],
+  ]
+  
+  s.files         = Dir['**/*']
+  s.test_files    = Dir['test/**/*'] + Dir['spec/**/*']
+  s.executables   = Dir['bin/*'].map { |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  
+  ## Make sure you can build the gem on older versions of RubyGems too:
+  s.rubygems_version = APISpec::VERSION.dup
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.specification_version = 3 if s.respond_to? :specification_version
+  
+  dependencies.each do |type, name, version|
+    if s.respond_to?("add_#{type}_dependency")
+      s.send("add_#{type}_dependency", name, version)
+    else
+      s.add_dependency(name, version)
+    end
+  end
+end

data/bin/apispec

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+require 'optparse'
+
+# grab the project root for tempaltes and the lib
+project_root = File.join(File.dirname(__FILE__), "..")
+
+require File.expand_path(File.join(project_root, "lib", "apispec"))
+
+# the default tempate dir
+template_dir = File.join(project_root, "templates")
+resource_dir = File.join(project_root, "resources")
+
+class DirectoryError < StandardError; end
+def require_directory!(dir)
+  dir = File.expand_path(dir)
+  raise DirectoryError.new("directory #{dir} doesn't exist!") unless File.exist? dir
+  dir
+end
+
+options = {
+  :workspace => File.expand_path("."),
+  :template => File.expand_path(template_dir),
+  :output => File.expand_path("apidoc"),
+  :resource => File.expand_path(resource_dir)
+}
+parser = nil
+
+begin
+  parser = OptionParser.new do |opts|
+    opts.banner = "Usage: #{$0} [options]"
+    opts.version = APISpec::VERSION
+  
+    opts.separator ""
+    opts.separator "No existing project options:"
+  
+    opts.on("-c", "--create <name>", "create a new project") do |name|
+      options[:create] = name
+    end
+  
+    opts.separator ""
+    opts.separator "Project options:"
+
+    opts.on("-w", "--workspace <dir>", 
+            "The directory containing the source files (default: .)") do |dir|
+      options[:workspace] = require_directory!(dir)
+    end
+  
+    opts.on("-t", "--template <dir>", 
+            "The template directory (default: bundled with apispec)") do |dir|
+      options[:template] = require_directory!(dir)
+    end
+    
+    opts.on("-r", "--rescoure <dir>", 
+            "The resource directory (default: bundled with apispec)") do |dir|
+      options[:template] = require_directory!(dir)
+    end
+    
+    opts.on("-p", "--print", 
+            "The resource directory (default: bundled with apispec)") do
+      options[:print] = true
+    end
+
+    opts.on("-o", "--output <dir>", 
+            "The output directory (default: apidoc)") do |dir|
+      options[:output] = File.expand_path(dir)
+    end
+
+    # opts.on("-s", "--server <port>", "Don't create a output folder start a server on given port") do |dir|
+    #   options[:output] = dir
+    # end
+
+    opts.separator ""
+    opts.separator "Common options:"
+  
+    opts.on("-v", "--verbose", "Run verbosely") do
+      options[:verbose] = true
+    end
+  end
+  parser.parse!
+rescue DirectoryError => ex
+  STDERR.puts "Invalid Argument: #{ex.message}"
+  STDERR.puts parser.help
+  exit 3
+rescue OptionParser::ParseError => ex
+  STDERR.puts ex.message
+  STDERR.puts parser.help
+  exit 2
+end
+
+if options[:print]
+  # just print the structure
+  generator = APISpec::Generator.new(options)
+  generator.parse_files!
+  puts generator.namespace.print_tree()
+elsif dir = options[:create]
+  # create a new project based on the example project
+  new_dir = File.expand_path(dir)
+  FileUtils.mkdir_p(new_dir)
+  FileUtils.cp_r(Dir[File.expand_path(File.join(project_root, "example", "*"))], 
+                 new_dir)
+elsif Dir[File.join(options[:workspace], "**", "*.rb")].any?
+  begin
+    APISpec::Generator.new(options).start!
+  rescue APISpec::Namespace::ReferenceError => ex
+    STDERR.puts ex.message
+    exit 4
+  end
+else
+  STDERR.puts "There are no files to generate a documentation from!"
+  STDERR.puts parser.help
+  exit 5
+end

data/example/datagram/user.json

@@ -0,0 +1,7 @@
+{
+  "id": 0,
+  "firstname": "John",
+  "lastname": "Doe",
+  "login": "john.doe",
+  "password": "secretxxx"
+}

data/example/example.rb

@@ -0,0 +1,59 @@
+field "X-User", "UserID" do
+  desc "The users email address"
+  example "test@example.com"
+end
+
+field "folder_id", "FolderID" do
+  desc "unique id of folder for user"
+end
+
+object "Folder" do
+  fields "FolderID"
+  example :text, %q{
+    asd
+  }
+end
+
+interface "Folders" do
+  base_uri "http://example.com/mail-rest"
+  
+  get 'folders' do
+    desc "returns the list of folders"
+  
+    request do
+      headers "UserID"
+    end
+    
+    response do
+      example :json, %q|
+{
+  "Kreditkarte" : "Xema",
+  "Nummer"      : "1234-5678-9012-3456",
+  "Inhaber"       : {
+    "Name"        : "Reich",
+    "Vorname"     : "Rainer",
+    "Geschlecht"  : "männlich",
+    "Vorlieben"   : [ "Reiten", "Schwimmen", "Lesen" ],
+    "Alter"       : null
+  },
+  "Deckung"     : 2e+6,
+  "Währung"     : "EURO"
+}
+      |
+      array "Folder"
+    end
+  end
+  
+  get 'folder/:folder_id' do
+    desc "returns the mail header objects of the requested Folder"
+  
+    request do
+      headers "UserID"
+      params "FolderID"
+    end
+    
+    response do
+      object "Folder"
+    end
+  end
+end

data/example/user.rb

@@ -0,0 +1,34 @@
+namespace "Account" do
+  field("id")        { type :integer }
+  field("firstname") { example "John" }
+  field("lastname")  { example "Doe" }
+  field("login")     { example "john.doe" }
+  field("password")  { example "secretxxx" }
+  
+  object "User" do
+    fields "Account.id", "Account.firstname", "Account.lastname", 
+           "Account.login", "Account.password"
+    example_file :json, "datagram/user.json"
+  end
+  
+  interface "UserRest" do
+    base_uri "/account"
+    
+    get "users/" do
+      response do
+        array "Account.User" 
+        example_file :json, "datagram/user.json"
+      end
+    end  
+  end
+end
+
+interface "SystemCheck" do
+  get "check" do
+    desc "returns true if the system is ok otherwise false"
+    
+    response do
+      example :text, "OK"
+    end
+  end
+end

data/lib/apispec/example.rb

@@ -0,0 +1,10 @@
+class APISpec::Example
+  def initialize(format, example)
+    @format = format
+    @example = example
+  end
+  
+  def to_html(message)
+    CodeRay.scan(@example, @format).div
+  end
+end

data/lib/apispec/field.rb

@@ -0,0 +1,37 @@
+class APISpec::Field < APISpec::Node  
+  # default type is String and field is not optional
+  def initialize(name, &block)
+    @optional = false
+    @nullable = false
+    @type = :string
+    super(name, &block)
+  end
+
+  def type(value)
+    @type = value
+  end
+
+  def desc(value)
+    @desc = value
+  end
+
+  def default(value)
+    @default = value
+  end
+
+  def optional(value)
+    @optional = value
+  end
+
+  def nullable(value)
+    @nullable = value
+  end
+
+  def example(value)
+    @example = value
+  end
+  
+  def resolve_references!(root_namespace)
+    @type = root_namespace.find_object(@type) if @type.is_a? String
+  end
+end

data/lib/apispec/generator.rb

@@ -0,0 +1,104 @@
+require "logger"
+require "fileutils"
+
+class APISpec::Generator
+  attr_reader :namespace, :logger
+  
+  def initialize(options)
+    @options = options
+    # logging
+    @logger = Logger.new(STDOUT)
+    @logger.level = Logger::WARN unless options[:verbose]
+    @logger.formatter = proc do |severity, datetime, progname, msg|
+      "#{datetime.strftime("%Y-%m-%d %H:%M:%S")} [#{severity}]: #{msg}\n"
+    end
+    @namespace = APISpec::Namespace.new(nil)
+  end
+  
+  # returns the dir with the root based in the working directory
+  def path(dir)
+    File.join(@options[:workspace], dir)
+  end
+  
+  # read all ruby files that can be found in the working directory
+  def parse_files!
+    @logger.info "parse all files"
+    Dir[File.join(@options[:workspace], "**", "*.rb")].each do |path|
+      logger.info "read file #{path}..."
+      @namespace.read_file(path)
+    end
+  end
+  
+  # creates the output folder
+  def create_output_folder!
+    @logger.info "remove and create the output folder"
+    FileUtils.rm_rf "#{@options[:output]}"
+    FileUtils.mkdir_p @options[:output]
+  end
+  
+  # create the index frame
+  def create_index!
+    @logger.info "create index frame"
+    File.open(File.join("#{@options[:output]}", "index.html"), "w") do |file|
+      file.write(template(binding, :index))
+    end    
+  end
+  
+  # create the links page (left part of frame)
+  def create_links!
+    @logger.info "create links page"
+    File.open(File.join("#{@options[:output]}", "links.html"), "w") do |file|
+      file.write(template(binding, :links))
+    end
+  end
+  
+  # create the documentation files itself
+  def create_objects_and_interfaces!
+    @namespace.objects.each do |object|
+      create(object)
+    end
+    @namespace.interfaces.each do |interface|
+      create(interface)
+    end
+  end
+  
+  # create the resources for all subfolders and main folder
+  def create_resources!
+    Dir[File.join(@options[:output], "**/*")].map do |path|
+      File.dirname(File.expand_path(path))
+    end.uniq.each do |path|
+      @logger.info "copy template resources to #{path}"
+      FileUtils.cp Dir[File.join(@options[:resource], "*")], path
+    end
+  end
+  
+  # start the generator
+  def start!
+    parse_files!
+    create_output_folder!
+    create_index!
+    create_links!
+    create_objects_and_interfaces!
+    create_resources!
+  end
+
+  # render a template with the passed object as binding
+  def template(object, template_name)
+    path = File.join(@options[:template], "#{template_name}.html.erb")
+    erb = ERB.new(File.read(path))
+    erb.filename = path
+    erb.result(object)
+  end
+
+  # create a doc file for the passed node
+  def create(node)
+    dir = File.dirname(node.to_path)
+    file_name = File.basename(node.to_path)
+    path = File.join("#{@options[:output]}", dir)
+    FileUtils.mkdir_p path
+    File.open(File.join(path, file_name), "w") do |file|
+      @logger.info "create page for #{node}"
+      file.write(node.to_html(self))
+    end
+  end
+end

data/lib/apispec/http.rb

@@ -0,0 +1,53 @@
+module APISpec
+  HTTP_STATUS_CODES = {
+    100 => "Continue",
+    101 => "Switching Protocols",
+    102 => "Processing",
+    200 => "OK",
+    201 => "Created",
+    202 => "Accepted",
+    203 => "Non-Authoritative Information",
+    204 => "No Content",
+    205 => "Reset Content",
+    206 => "Partial Content",
+    207 => "Multi-Status",
+    226 => "IM Used",
+    300 => "Multiple Choices",
+    301 => "Moved Permanently",
+    302 => "Found",
+    303 => "See Other",
+    304 => "Not Modified",
+    305 => "Use Proxy",
+    307 => "Temporary Redirect",
+    400 => "Bad Request",
+    401 => "Unauthorized",
+    402 => "Payment Required",
+    403 => "Forbidden",
+    404 => "Not Found",
+    405 => "Method Not Allowed",
+    406 => "Not Acceptable",
+    407 => "Proxy Authentication Required",
+    408 => "Request Timeout",
+    409 => "Conflict",
+    410 => "Gone",
+    411 => "Length Required",
+    412 => "Precondition Failed",
+    413 => "Request Entity Too Large",
+    414 => "Request-URI Too Long",
+    415 => "Unsupported Media Type",
+    416 => "Requested Range Not Satisfiable",
+    417 => "Expectation Failed",
+    422 => "Unprocessable Entity",
+    423 => "Locked",
+    424 => "Failed Dependency",
+    426 => "Upgrade Required",
+    500 => "Internal Server Error",
+    501 => "Not Implemented",
+    502 => "Bad Gateway",
+    503 => "Service Unavailable",
+    504 => "Gateway Timeout",
+    505 => "HTTP Version Not Supported",
+    507 => "Insufficient Storage",
+    510 => "Not Extended"
+  }
+end

data/lib/apispec/interface.rb

@@ -0,0 +1,29 @@
+class APISpec::Interface < APISpec::Node
+  def initialize(name, &block)
+    @resources = []
+    super(name, &block)
+  end
+
+  def base_uri(value = nil)
+    @base_uri ||= value
+  end
+  
+  def get(path, &block);      http(:get, path, &block);     end
+  def put(path, &block);      http(:put, path, &block);     end
+  def post(path, &block);     http(:post, path, &block);    end
+  def delete(path, &block);   http(:delete, path, &block);  end
+  def options(path, &block);  http(:options, path, &block); end
+  def head(path, &block);     http(:head, path, &block);    end
+  def trace(path, &block);    http(:trace, path, &block);   end
+  def connect(path, &block);  http(:connect, path, &block); end
+
+  def http(method, path, &block)
+    @resources << APISpec::Resource.new(method, path, &block)
+  end
+  
+  def resolve_references!(root_namespace)
+    @resources.each do |resource|
+      resource.resolve_references!(root_namespace)
+    end
+  end
+end

data/lib/apispec/message.rb

@@ -0,0 +1,56 @@
+class APISpec::Message
+  def initialize(&block)
+    @headers = []
+    @parameters = []
+    instance_eval(&block)
+  end
+
+  def headers(*value)
+    @headers = value
+  end
+
+  def params(*value)
+    @parameters = value
+  end
+
+  def desc(value)
+    @desc = value
+  end
+  
+  def object(value)
+    @object = value
+  end
+  
+  def array(value)
+    @array = value
+  end
+  
+  def content_desc(value)
+    @content_desc = value
+  end
+
+  def example(format, value)
+    @example = APISpec::Example.new(format, value)
+  end
+  
+  def example_file(format, path)
+    @example = [format, path]
+  end
+  
+  def resolve_references!(root_namespace)
+    @headers    = @headers.map    { |name| root_namespace.find_field(name) }.flatten
+    @parameters = @parameters.map { |name| root_namespace.find_field(name) }.flatten
+    @object     = root_namespace.find_object(@object) if @object
+    @array      = root_namespace.find_object(@array) if @array
+  end
+  
+  def to_html(generator, resource)
+    @generator = generator
+    @resource = resource
+    if @example.is_a? Array
+      format, path = @example
+      @example = APISpec::Example.new(format, File.read(@generator.path(path)))
+    end
+    generator.template(binding, :message)
+  end
+end

data/lib/apispec/namespace.rb

@@ -0,0 +1,113 @@
+class APISpec::Namespace < APISpec::Node
+  class AlreadyDefinedError < StandardError; end
+  class ReferenceError < StandardError; end
+  
+  def initialize(name, &block)
+    @nodes = {}
+    super(name, &block)
+  end
+  
+  # reads the passed file
+  def read_file(path)
+    eval(File.read(path), binding, path)
+  end
+  
+  def find_field(path)
+    result = find(path)
+    if result.is_a? Array
+      result.map { |path| find(path) }
+    else
+      [result]
+    end
+  end
+  
+  def find_object(path)
+    find(path)
+  end
+  
+  def find(path)
+    path_parts = path.split(".")
+    node = self
+    while path_parts.any?
+      node = node.find_node(path_parts.shift)
+      raise ReferenceError.new("#{path} not found in #{self.to_s}") unless node
+    end
+    node
+  end
+  
+  def all(method, type)
+    nodes = []
+    @nodes.keys.sort.each do |name|
+      node = @nodes[name]
+      if node.is_a? APISpec::Namespace
+        nodes << node.send(method)
+      elsif node.is_a? type
+        nodes << node
+      end
+    end
+    nodes.flatten
+  end
+  
+  def interfaces
+    all(:interfaces, APISpec::Interface)
+  end
+  
+  def objects
+    all(:objects, APISpec::Object)    
+  end
+  
+  def find_node(name)
+    @nodes[name]
+  end
+    
+  def to_s
+    "#{super} (Nodes: #{@nodes.size})"
+  end
+  
+  # print the structure of all namespaces
+  def print_tree(indent = 0, lines = [])
+    lines << ("  " * indent) + self.to_s
+    @nodes.keys.sort.each do |reference|
+      node = @nodes[reference]
+      if node.is_a? APISpec::Namespace
+        node.print_tree(indent + 1, lines)
+      else
+        lines << ("  " * (indent + 1)) + "#{reference} => #{node.to_s}"
+      end
+    end
+    lines.join("\n")
+  end
+  
+  def namespace(name, &block)
+    if node = @nodes[name]
+      node.instance_eval &block
+    else
+      define_node name, APISpec::Namespace.new(name, &block)
+    end
+  end
+  
+  def define_node(name, node)
+    raise AlreadyDefinedError.new("#{name} is already defined!") if @nodes[name]
+    @nodes[name] = node
+    node.parent = self if node.respond_to? :parent
+  end
+  
+  def interface(name, reference = nil, &block)
+    reference = reference || name
+    define_node name, APISpec::Interface.new(name, &block)
+  end
+  
+  def object(name, reference = nil, &block)
+    reference = reference || name
+    define_node reference, APISpec::Object.new(name, &block)
+  end
+  
+  def field(name, reference = nil, &block)
+    reference = reference || name
+    define_node reference, APISpec::Field.new(name, &block)
+  end
+  
+  def field_set(reference = nil, *fields)
+    define_node reference, fields
+  end
+end