fdoc 0.2.1

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org/"
+gemspec

data/README.md

@@ -0,0 +1,120 @@
+# fdoc: Documentation format and verification
+
+High-quality documentation is extremely useful, but maintaining it is often a pain. We aim to create a tool to facilitate easy creation and maintenance of API documentation.
+
+In a Rails app, fdoc can help document an API as well as verify that requests and responses adhere to their appropriate schemata.
+
+Outside a Rails app, fdoc can provide a common format for API documentation, as well as the ability to generate basic HTML pages for humans to consume.
+
+fdoc is short for Farnsdocs. They are named for everybody's favorite, good news-bearing, crotchety old man, Professor Farnsworth.
+
+![Professor Farnsworth][github_img]
+
+## Usage
+
+### In a Rails app
+
+Add fdoc to your Gemfile.
+
+    gem 'fdoc'
+
+Tell fdoc where to look for .fdoc files. By default, fdoc will look in `docs/fdoc`, but you can change this behavior to look anywhere. This fits best in something like a spec\_helper file.
+
+    require 'fdoc'
+
+    Fdoc.service_path = "path/to/your/fdocs"
+
+fdoc is built to work around controller specs in rspec, and provides `Fdoc::SpecWatcher` as a mixin. Make sure to include it *inside* your top level describe.
+
+    require 'fdoc/spec_watcher'
+
+    describe MembersController do
+      include Fdoc::SpecWatcher
+      ...
+    end
+
+To enable fdoc for an endpoint, add the `fdoc` option with the path to the endpoint. fdoc will intercept all calls to `get`, `post`, `put`, and `delete` and verify those parameters accordingly.
+
+    context "#show", :fdoc => 'members/list' do
+      ..
+    end
+
+fdoc also has a scaffolding mode, where it attemps to infer the schema of a request based on sample responses. The interface is exactly the same as verifying, just set the environment variable `FDOC_SCAFFOLD=true`.
+
+    FDOC_SCAFFOLD=true bundle exec rspec spec/controllers
+
+For more information on scaffolding, please see the more in-depth [fdoc scaffolding example][github_scaffold].
+
+### Outside a Rails App
+
+fdoc provides the `fdoc_to_html` script to transform a directory of `.fdoc` files into more human-readable HTML.
+
+In this repo, try running:
+
+    bin/fdoc_to_html spec/fixtures html
+
+## Example
+
+`.fdoc` files are YAML files based on [JSON schema][json_schema] to describe API endpoints. They derive their endpoint path and verb from their filename.
+
+- For more information on fdoc file naming conventions, please see the [fdoc file conventions guide][github_files].
+- For more information on how fdoc uses JSON schema, please see the [json schema usage document][github_json].
+
+Here is `members/list-POST.fdoc`:
+
+    description: The list of members.
+    requestParameters:
+      properties:
+        limit:
+          type: integer
+          required: no
+          default: 50
+          description: Limits the number of results returned, used for paging.
+    responseParameters:
+      properties:
+        members:
+          type: array
+          items:
+            title: member
+            description: Representation of a member
+            type: object
+            properties:
+              name:
+                description: Member's name
+                type: string
+                required: yes
+                example: Captain Smellypants
+    responseCodes:
+    - status: 200 OK
+      successful: yes
+      description: A list of current members
+    - status: 400 Bad Request
+      successful: no
+      description: Indicates malformed parameters
+
+
+## Goals
+
+- Client engineers should be able to participate in documenting an API and
+  keeping it up to date.
+- Server engineers should be able to test their implementations.
+- The documentation should be as close to the code as possible.
+  - Branches, reviews, and merges are the appropriate way to update the docs.
+  - Experimental drafts should just live on branches and never get
+    merged into master.
+- Specification alone is not enough, there needs to be room for discussion.
+
+## Contributing
+
+Just fork and make a pull request! You will need to sign the [Individual Contributor License Agreement (CLA)][contrib_license] before we can merge your code.
+
+
+
+
+[github_img]: https://github.com/square/fdoc/raw/master/docs/farnsworth.png
+[github_scaffold]: https://github.com/square/fdoc/blob/master/docs/scaffold.md
+[github_json]: https://github.com/square/fdoc/blob/master/docs/json_schema.md
+[github_files]: https://github.com/square/fdoc/blob/master/docs/files.md
+
+[json_schema]: http://json-schema.org/
+[contrib_license]: https://spreadsheets.google.com/spreadsheet/viewform?formkey=dDViT2xzUHAwRkI3X3k5Z0lQM091OGc6MQ&ndplr=1

data/Rakefile

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

data/bin/fdoc_to_html

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+
+require File.join(File.dirname(__FILE__), '../lib/fdoc')
+
+if ARGV.length < 2
+  exec_name = File.basename($0)
+  abort "Usage: #{exec_name} [fdoc_directory] [html_directory] (url_base_path)"
+end
+
+fdoc_directory, html_directory, url_base_path = ARGV[0..2]
+fdoc_directory = File.expand_path(fdoc_directory)
+html_directory = File.expand_path(html_directory)
+
+html_options = {
+  :html_directory => html_directory,
+  :static_html => true,
+  :url_base_path => url_base_path
+}
+
+def mkdir(dirname)
+  `mkdir -p #{dirname}` unless File.directory?(dirname)
+end
+
+mkdir(html_directory)
+
+meta_service = Fdoc::MetaService.new(fdoc_directory)
+services = if !meta_service.empty?
+  meta_service.services
+else
+  Array(Fdoc::Service.new(fdoc_directory))
+end
+
+if !meta_service.empty?
+  meta_service_presenter= Fdoc::MetaServicePresenter.new(
+    meta_service, html_options
+  )
+
+  index_html_path = File.join(html_directory, "index.html")
+  File.open(index_html_path, "w") do |file|
+    file.write(meta_service_presenter.to_html)
+
+    puts "created #{index_html_path}"
+  end
+end
+
+css_path = File.join(File.dirname(__FILE__), '../lib/fdoc/templates/styles.css')
+`cp "#{css_path}" "#{html_directory}"`
+puts "created #{File.expand_path(css_path)}"
+
+services.each do |service|
+  service_presenter = Fdoc::ServicePresenter.new(service, html_options)
+  html_sub_directory = if meta_service.empty?
+    html_directory
+  else
+    File.join(html_directory, service_presenter.slug_name)
+  end
+  
+  mkdir(html_sub_directory)
+
+  index_html_path = File.join(html_sub_directory, "index.html")
+  File.open(index_html_path, "w") do |file|
+    file.write(service_presenter.to_html)
+
+    puts "created #{index_html_path}"
+  end
+
+  service_presenter.endpoints.flatten.each do |endpoint|
+    endpoint_html_path = File.join(html_sub_directory, endpoint.url)
+    mkdir(File.dirname(endpoint_html_path))
+
+    File.open(endpoint_html_path, "w") do |file|
+      file.write(endpoint.to_html)
+
+      puts "created #{endpoint_html_path}"
+    end
+  end
+end

data/fdoc.gemspec

@@ -0,0 +1,36 @@
+# encoding: utf-8
+
+Gem::Specification.new do |s|
+  s.name = "fdoc"
+
+  s.version = File.read("#{File.dirname(__FILE__)}/VERSION")
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.rubygems_version = "1.3.7"
+
+  s.authors = ["Matt Wilson", "Zach Margolis", "Sean Sorrell"]
+  s.email = "support@squareup.com"
+
+  s.date = "2011-11-07"
+  s.description = "A tool for documenting API endpoints."
+  s.summary = "A tool for documenting API endpoints."
+  s.homepage = "http://github.com/square/fdoc"
+
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.require_paths = ["lib"]
+  s.files = Dir['{lib,spec}/**/*'] + %w(fdoc.gemspec Rakefile README.md Gemfile)
+  s.test_files = Dir['spec/**/*']
+  s.bindir        = "bin"
+  s.executables  << "fdoc_to_html"
+
+  s.add_dependency("json")
+  s.add_dependency("json-schema", ">= 1.0.1")
+  s.add_dependency("kramdown")
+
+  s.add_development_dependency("rake")
+  s.add_development_dependency("rspec", "~> 2.5")
+  s.add_development_dependency("nokogiri")
+  s.add_development_dependency("cane")
+end

data/lib/endpoint-schema.yaml

@@ -0,0 +1,30 @@
+type: object
+title: endpoint
+description: Describes an API endpoint
+additionalProperties: no
+properties:
+  description:
+    type: string
+    required: no
+    description: Free-form text describing the endpoint. Rendered with a Markdown parser.
+  requestParameters:
+    type: object
+    description: A schema for the request parameters
+  responseParameters:
+    type: object
+    description: A schema for the response parameters
+  responseCodes:
+    type: array
+    required: yes
+    items:
+      type: object
+      description: |
+        A status code is defined by its HTTP status code and whether or not it was successful
+      properties:
+        status:
+          type: string
+          description: An HTTP status code, such as 200 OK or 201 Created
+        successful:
+          type: boolean
+          description: |
+            Describes if the client can interpret this response as successful.

data/lib/fdoc.rb

@@ -0,0 +1,46 @@
+$:.unshift(File.dirname(__FILE__))
+
+module Fdoc
+  DEFAULT_SERVICE_PATH = "docs/fdoc"
+
+  def self.scaffold_mode?
+    ENV['FDOC_SCAFFOLD']
+  end
+
+  def self.service_path=(service_path)
+    @service_path = service_path
+  end
+
+  def self.service_path
+    @service_path || DEFAULT_SERVICE_PATH
+  end
+
+  def self.decide_success_with(&block)
+    @success_block = block
+  end
+
+  def self.decide_success(*args)
+    if @success_block
+      @success_block.call(*args)
+    else
+      true
+    end
+  end
+
+  # Top-level fdoc validation error, abstract.
+  class ValidationError < StandardError; end
+
+  # Indicates an unknown response code.
+  class UndocumentedResponseCode < ValidationError; end
+end
+
+require 'fdoc/service'
+require 'fdoc/meta_service'
+require 'fdoc/endpoint'
+require 'fdoc/endpoint_scaffold'
+require 'fdoc/presenters/html_presenter'
+require 'fdoc/presenters/service_presenter'
+require 'fdoc/presenters/meta_service_presenter'
+require 'fdoc/presenters/endpoint_presenter'
+require 'fdoc/presenters/schema_presenter'
+require 'fdoc/presenters/response_code_presenter'

data/lib/fdoc/endpoint.rb

@@ -0,0 +1,110 @@
+require 'yaml'
+require 'json-schema'
+
+# Endpoints represent the schema for an API endpoint
+# The #consume_* methods will raise exceptions if input differs from the schema
+class Fdoc::Endpoint
+  attr_reader :service
+  attr_reader :endpoint_path
+
+  def initialize(endpoint_path, service=Fdoc::Service::DefaultService)
+    @endpoint_path = endpoint_path
+    @schema = YAML.load_file(@endpoint_path)
+    @service = service
+  end
+
+  def consume_request(params, successful=true)
+    if successful
+      schema = set_additional_properties_false_on(request_parameters.dup)
+      JSON::Validator.validate!(schema, stringify_keys(params))
+    end
+  end
+
+  def consume_response(params, status_code, successful=true)
+    response_code = response_codes.find do |rc|
+      rc["status"] == status_code && rc["successful"] == successful
+    end
+
+    if !response_code
+      raise Fdoc::UndocumentedResponseCode,
+        'Undocumented response: %s, successful: %s' % [
+          status_code, successful
+        ]
+    elsif successful
+      schema = set_additional_properties_false_on(response_parameters.dup)
+      JSON::Validator.validate!(schema, stringify_keys(params))
+    else
+      true
+    end
+  end
+
+  def verb
+    @verb ||= endpoint_path.match(/([A-Z]*)\.fdoc$/)[1]
+  end
+
+  def path
+    @path ||= endpoint_path.
+                gsub(service.service_dir, "").
+                match(/\/?(.*)[-\/][A-Z]+\.fdoc/)[1]
+  end
+
+  # properties
+
+  def deprecated?
+    @schema["deprecated"]
+  end
+
+  def description
+    @schema["description"]
+  end
+
+  def request_parameters
+    @schema["requestParameters"] ||= {}
+  end
+
+  def response_parameters
+    @schema["responseParameters"] ||= {}
+  end
+
+  def response_codes
+    @schema["responseCodes"] ||= []
+  end
+
+  protected
+
+  # default additionalProperties on objects to false
+  # create a copy, so we don't mutate the input
+  def set_additional_properties_false_on(value)
+    if value.kind_of? Hash
+      copy = value.dup
+      if value["type"] == "object" || value.has_key?("properties")
+        copy["additionalProperties"] ||= false
+      end
+      value.each do |key, hash_val|
+        unless key == "additionalProperties"
+          copy[key] = set_additional_properties_false_on(hash_val)
+        end
+      end
+      copy
+    elsif value.kind_of? Array
+      copy = value.map do |arr_val|
+        set_additional_properties_false_on(arr_val)
+      end
+    else
+      value
+    end
+  end
+
+  def stringify_keys(obj)
+    case obj
+    when Hash
+      result = {}
+      obj.each do |k, v|
+        result[k.to_s] = stringify_keys(v)
+      end
+      result
+    when Array then obj.map { |v| stringify_keys(v) }
+    else obj
+    end
+  end
+end

data/lib/fdoc/endpoint_scaffold.rb

@@ -0,0 +1,132 @@
+# EndpointScaffolds aggregate input to guess at the structure of an API
+# endpoint. The #consume_* methods can modify the structure of the
+# in-memory endpoint, to save the results to the file system, call #persist!
+class Fdoc::EndpointScaffold < Fdoc::Endpoint
+  def initialize(endpoint_path, service=Fdoc::Service::DefaultService)
+    if File.exist?(endpoint_path)
+      super
+    else
+      @endpoint_path = endpoint_path
+      @schema = {
+        "description" => "???",
+        "responseCodes" => []
+      }
+      @service = service
+    end
+  end
+
+  def persist!
+    dirname = File.dirname(@endpoint_path)
+    Dir.mkdir(dirname) unless File.directory?(dirname)
+
+    File.open(@endpoint_path, "w") do |file|
+      YAML.dump(@schema, file)
+    end
+  end
+
+  def consume_request(params, successful = true)
+    scaffold_schema(request_parameters, stringify_keys(params), {
+      :root_object => true
+    })
+  end
+
+  def consume_response(params, status_code, successful=true)
+    if successful
+      scaffold_schema(response_parameters, stringify_keys(params), {
+        :root_object => true
+      })
+    end
+
+    response_code = response_codes.find do
+      |rc| rc["status"] == status_code && rc["successful"] == successful
+    end
+
+    if !response_code
+      response_codes << {
+        "status" => status_code,
+        "successful" => successful,
+        "description" => "???"
+      }
+    end
+  end
+
+  protected
+
+  def scaffold_schema(schema, params, options = {:root_object => false})
+    unless options[:root_object]
+      schema["description"] ||= "???"
+      schema["required"] = "???" unless schema.has_key?("required")
+    end
+
+    if params.kind_of? Hash
+      scaffold_hash(schema, params, options)
+    elsif params.kind_of? Array
+      scaffold_array(schema, params, options)
+    else
+      scaffold_atom(schema, params, options)
+    end
+  end
+
+  def scaffold_hash(schema, params, options = {})
+    schema["type"] ||= "object" unless options[:root_object]
+    schema["properties"] ||= {}
+
+    params.each do |key, value|
+      unless schema[key]
+        schema["properties"][key] ||= {}
+        sub_options = options.merge(:root_object => false)
+        scaffold_schema(schema["properties"][key], value, sub_options)
+      end
+    end
+  end
+
+  def scaffold_array(schema, params, options = {})
+    schema["type"] ||= "array"
+    schema["items"] ||= {}
+    params.each do |arr_value|
+      sub_options = options.merge(:root_object => false)
+      scaffold_schema(schema["items"], arr_value, options.merge(sub_options))
+    end
+  end
+
+  def scaffold_atom(schema, params, options = {})
+    value = params
+    schema["type"] ||= guess_type(params)
+    if format = guess_format(params)
+      schema["format"] ||= format
+    end
+    schema["example"] ||= value
+  end
+
+  def guess_type(value)
+    in_type = value.class.to_s
+    type_map = {
+      "Fixnum" => "integer",
+      "Float" => "number",
+      "Hash" => "object",
+      "Time" => "string",
+      "TrueClass" => "boolean",
+      "FalseClass" => "boolean",
+      "NilClass" => "null"
+    }
+    type_map[in_type] || in_type.downcase
+  end
+
+  def guess_format(value)
+    if value.kind_of? Time
+      "date-time"
+    elsif value.kind_of? String
+      if value.start_with? "http://"
+        "uri"
+      elsif value.match(/\#[0-9a-fA-F]{3}(?:[0-9a-fA-F]{3})?\b/)
+        "color"
+      else
+        begin
+          "date-time" if Time.iso8601(value)
+        rescue
+          nil
+        end
+      end
+    end
+  end
+end