fdoc 0.2.1

data/spec/fdoc/presenters/endpoint_presenter_spec.rb

@@ -0,0 +1,93 @@
+require 'spec_helper'
+require 'nokogiri'
+
+describe Fdoc::EndpointPresenter do
+  subject {
+    described_class.new(endpoint)
+  }
+
+  let (:test_service) { Fdoc::Service.new('spec/fixtures') }
+  let (:endpoint) { Fdoc::Endpoint.new("spec/fixtures/members/list/GET.fdoc", test_service) }
+
+  context "#to_html" do
+    it "should generate valid HTML" do
+      html = subject.to_html
+
+      expect {
+        Nokogiri::HTML(html) { |config| config.strict }
+      }.to_not raise_exception
+    end
+  end
+
+  context "#example_from_schema" do
+    example_schema_yaml = <<-EOS
+    properties:
+      name:
+        type: string
+        example: Bobby Brown
+      achievements:
+        type: array
+        items:
+          type: string
+          example: Most Bugs Squashed
+      check_in_count:
+        type: integer
+        example: 52
+      friends:
+        type: array
+        items:
+          properties:
+            name:
+              type: string
+              example: Freddy Friend
+            id:
+              type: integer
+              example: 12345
+      email:
+        type: string
+      address:
+        properties:
+          street_number:
+            type: integer
+            example: 1234
+          street_name:
+            type: string
+            example: Main St.
+          state:
+            type: string
+            example: CA
+          zip:
+            type: integer
+            example: 91234
+      homepage_url:
+        type: ['string', 'null']
+        format: uri
+        example: http://my.website.com
+    EOS
+    example_schema = YAML.load(example_schema_yaml)
+
+    expected_example = {
+      "name" => "Bobby Brown",
+      "achievements" => ["Most Bugs Squashed"],
+      "check_in_count" => 52,
+      "email" => "",
+      "friends" => [
+        {
+          "name" => "Freddy Friend",
+          "id" => 12345
+        }
+      ],
+      "address" => {
+        "street_number" => 1234,
+        "street_name" => "Main St.",
+        "state" => "CA",
+        "zip" => 91234
+      },
+      "homepage_url" => "http://my.website.com"
+    }
+
+    it "should generate an example response from the contents of the schema" do
+      subject.example_from_schema(example_schema).should == expected_example
+    end
+  end
+end

data/spec/fdoc/presenters/service_presenter_spec.rb

@@ -0,0 +1,18 @@
+require 'spec_helper'
+require 'nokogiri'
+
+describe Fdoc::ServicePresenter do
+  subject {
+    Fdoc::ServicePresenter.new(Fdoc::Service.new('spec/fixtures'))
+  }
+
+  context "#to_html" do
+    it "should generate valid HTML" do
+      html = subject.to_html
+
+      expect {
+        Nokogiri::HTML(html) { |config| config.strict }
+      }.to_not raise_exception
+    end
+  end
+end

data/spec/fdoc/service_spec.rb

@@ -0,0 +1,63 @@
+require 'spec_helper'
+
+describe Fdoc::Service do
+  subject { described_class.new('spec/fixtures') }
+
+  let(:verb) { 'GET' }
+  let(:path) { 'members/list' }
+
+  describe "#open" do
+    let(:scaffold_mode) { false }
+    context "in regular mode" do
+      it "returns an Endpoint object" do
+        endpoint = subject.open(verb, path, scaffold_mode)
+        endpoint.should     be_kind_of(Fdoc::Endpoint)
+        endpoint.should_not be_kind_of(Fdoc::EndpointScaffold)
+      end
+    end
+
+    context "in scaffold mode" do
+      let(:scaffold_mode) { true }
+
+      it "returns an EndpointScaffold object" do
+        subject.open(verb, path, scaffold_mode).should be_kind_of(Fdoc::EndpointScaffold)
+      end
+    end
+  end
+
+  describe "#path_for" do
+    let(:flat_file_name) { File.expand_path('spec/fixtures/members/list-GET.fdoc') }
+    let(:nested_file_name) { File.expand_path('spec/fixtures/members/list/GET.fdoc') }
+
+    context "when a flat named filename exists" do
+      before do
+        File.should_receive(:exist?).with(flat_file_name).and_return(true)
+      end
+
+      it "returns the flat named file path" do
+        subject.path_for(verb, path).should == flat_file_name
+      end
+    end
+
+    context "when a no flat named named file exists, but a nested path does" do
+      before do
+        File.should_receive(:exist?).with(flat_file_name).and_return(false)
+        File.should_receive(:exist?).with(nested_file_name).and_return(true)
+      end
+
+      it "returns the nested named file path" do
+        subject.path_for(verb, path).should == nested_file_name
+      end
+    end
+
+    context "when no file exists" do
+      before do
+        File.stub(:exist?).and_return(false)
+      end
+
+      it "returns the flat named file path" do
+        subject.path_for(verb, path).should == flat_file_name
+      end
+    end
+  end
+end

data/spec/fixtures/members/add-PUT.fdoc

@@ -0,0 +1,20 @@
+description: Add a new member
+requestParameters:
+  properties:
+    name:
+      type: string
+      required: yes
+      description: The name of the member to add, must be unique.
+      example: Max Power
+    email:
+      type: string
+      required: no
+      description: The email of the member to add
+      example: mpower@example.com
+responseCodes:
+  - status: 200 OK
+    successful: yes
+    description: Returns the member just added
+  - status: 400 Bad Request
+    successful: no
+    description: Member already exists

data/spec/fixtures/members/draft-POST.fdoc

@@ -0,0 +1,5 @@
+scaffold: yes
+description: Hypothetical endpoint, for testing scaffolding
+responseCodes:
+  - status: 200 OK
+    successful: yes

data/spec/fixtures/members/list/GET.fdoc

@@ -0,0 +1,50 @@
+description: The list of members.
+requestParameters:
+  properties:
+    limit:
+      type: integer
+      required: no
+      default: 50
+      description: Limits the number of results returned, used for paging.
+    offset:
+      type: integer
+      required: no
+      default: 0
+      description: Offsets the results returned, used for paging.
+    order_by:
+      type: string
+      enum:
+        - name
+        - email
+        - member_since
+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
+          email:
+            description: Member's email
+            type: string
+            required: no
+            example: smelly@pants.com
+          member_since:
+            description: The date the member joined
+            type: string
+            format: date-time
+            example: 2012-01-01T13:00:00Z
+responseCodes:
+  - status: 200 OK
+    successful: yes
+    description: A list of current members
+  - status: 400 Bad Request
+    successful: no
+    description: Indicates malformed parameters

data/spec/fixtures/members/list/complex-params-GET.fdoc

@@ -0,0 +1,94 @@
+requestParameters:
+  type: object
+  properties:
+    toplevel_param:
+      type: string
+      description: A paramater as normal
+      required: Yes
+    optional_nested_array:
+      type: array
+      required: No
+      items:
+        type: object
+        properties:
+          required_param:
+            required: Yes
+            description: It's required
+            type: string
+          optional_param:
+            required: Yes
+            description: It's optional
+            type: string
+    required_nested_array:
+      type: array
+      required: Yes
+      items:
+        type: object
+        properties:
+          required_param:
+            required: Yes
+            description: It's required
+            type: string
+          optional_param:
+            required: No
+            description: It's optional
+            type: string
+          optional_second_nested_object:
+            required: No
+            type: object
+            description: It's a bug
+            properties:
+              required_param:
+                required: Yes
+                description: It's required
+                type: string
+              optional_param:
+                required: No
+                description: It's optional
+                type: string
+          
+    optional_nested_object:
+      type: object
+      required: No
+      properties:
+        required_param:
+          required: Yes
+          description: It's required
+          type: string
+        optional_param:
+          required: No
+          description: It's optional
+          type: string
+    required_nested_object:
+      type: object
+      required: Yes
+      properties:
+        required_param:
+          required: Yes
+          description: It's required
+          type: string
+        optional_param:
+          required: No
+          description: It's optional
+          type: string
+        optional_second_nested_object:
+          required: No
+          type: object
+          description: It's a bug
+          properties:
+            required_param:
+              required: Yes
+              description: It's required
+              type: string
+            optional_param:
+              required: No
+              description: It's optional
+              type: string
+
+responseParameters:
+  type: string
+  description: Nothing important
+responseCodes:
+  - status: 200 OK
+    successful: yes
+    description: A list of current members

data/spec/fixtures/members/list/filter-GET.fdoc

@@ -0,0 +1,60 @@
+description: The list of members, filtered by params
+requestParameters:
+  type: object
+  properties:
+    limit:
+      type: integer
+      required: no
+      default: 50
+      description: Limits the number of results returned, used for paging.
+    offset:
+      type: integer
+      required: no
+      default: 0
+      description: Offsets the results returned, used for paging.
+    older_than:
+      type: string
+      format: date-time
+      required: no
+      description: |
+        If provided, results returned will only be updated before
+        the given date (exclusive)
+    newer_than:
+      type: string
+      format: date-time
+      required: no
+      description: |
+        If provided, results returned will only be updated after
+        the given date (inclusive)
+responseParameters:
+  type: object
+  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
+          email:
+            description: Member's email
+            type: string
+            required: no
+            example: smelly@pants.com
+          member_since:
+            description: The date the member joined
+            type: string
+            format: date-time
+            example: 2012-01-01T13:00:00Z
+responseCodes:
+  - status: 200 OK
+    successful: yes
+    description: A list of current members
+  - status: 400 Bad Request
+    successful: no
+    description: Indicates malformed parameters

data/spec/fixtures/members/members.fdoc.service

@@ -0,0 +1,11 @@
+name: Members API
+basePath: https://api.sample.com/members
+description: |
+  This service is used for lots of fun things
+  
+  * It would not make for a very exciting REST API, but
+    that's perfectly acceptable for a fixture file.
+  * These bullets are mostly to demonstrate Markdown interpolation
+discussion: |
+  This is room at the bottom of the page for more details about
+  this service.

data/spec/fixtures/sample_group.fdoc.meta

@@ -0,0 +1,9 @@
+name: fdoc Sample API
+description: |
+  This is a sample meta service, it encompasses only one service
+  for now.
+discussion: |
+  This is room at the bottom of the page for more details about
+  this service.
+services:
+  - ./members

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'fdoc'
+require 'rspec'

metadata

@@ -0,0 +1,174 @@
+--- !ruby/object:Gem::Specification
+name: fdoc
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+  prerelease: 
+platform: ruby
+authors:
+- Matt Wilson
+- Zach Margolis
+- Sean Sorrell
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-11-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: &70339438797600 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70339438797600
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: &70339438796920 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: *70339438796920
+- !ruby/object:Gem::Dependency
+  name: kramdown
+  requirement: &70339438796340 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70339438796340
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70339438792260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70339438792260
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70339438791760 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: *70339438791760
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: &70339438791300 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70339438791300
+- !ruby/object:Gem::Dependency
+  name: cane
+  requirement: &70339438790760 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70339438790760
+description: A tool for documenting API endpoints.
+email: support@squareup.com
+executables:
+- fdoc_to_html
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- lib/endpoint-schema.yaml
+- lib/fdoc/endpoint.rb
+- lib/fdoc/endpoint_scaffold.rb
+- lib/fdoc/meta_service.rb
+- lib/fdoc/presenters/endpoint_presenter.rb
+- lib/fdoc/presenters/html_presenter.rb
+- lib/fdoc/presenters/meta_service_presenter.rb
+- lib/fdoc/presenters/response_code_presenter.rb
+- lib/fdoc/presenters/schema_presenter.rb
+- lib/fdoc/presenters/service_presenter.rb
+- lib/fdoc/service.rb
+- lib/fdoc/spec_watcher.rb
+- lib/fdoc/templates/endpoint.html.erb
+- lib/fdoc/templates/meta_service.html.erb
+- lib/fdoc/templates/service.html.erb
+- lib/fdoc/templates/styles.css
+- lib/fdoc.rb
+- spec/fdoc/endpoint_scaffold_spec.rb
+- spec/fdoc/endpoint_spec.rb
+- spec/fdoc/presenters/endpoint_presenter_spec.rb
+- spec/fdoc/presenters/service_presenter_spec.rb
+- spec/fdoc/service_spec.rb
+- spec/fixtures/members/add-PUT.fdoc
+- spec/fixtures/members/draft-POST.fdoc
+- spec/fixtures/members/list/complex-params-GET.fdoc
+- spec/fixtures/members/list/filter-GET.fdoc
+- spec/fixtures/members/list/GET.fdoc
+- spec/fixtures/members/members.fdoc.service
+- spec/fixtures/sample_group.fdoc.meta
+- spec/spec_helper.rb
+- fdoc.gemspec
+- Rakefile
+- README.md
+- Gemfile
+- bin/fdoc_to_html
+homepage: http://github.com/square/fdoc
+licenses: []
+post_install_message: 
+rdoc_options:
+- --charset=UTF-8
+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.15
+signing_key: 
+specification_version: 3
+summary: A tool for documenting API endpoints.
+test_files:
+- spec/fdoc/endpoint_scaffold_spec.rb
+- spec/fdoc/endpoint_spec.rb
+- spec/fdoc/presenters/endpoint_presenter_spec.rb
+- spec/fdoc/presenters/service_presenter_spec.rb
+- spec/fdoc/service_spec.rb
+- spec/fixtures/members/add-PUT.fdoc
+- spec/fixtures/members/draft-POST.fdoc
+- spec/fixtures/members/list/complex-params-GET.fdoc
+- spec/fixtures/members/list/filter-GET.fdoc
+- spec/fixtures/members/list/GET.fdoc
+- spec/fixtures/members/members.fdoc.service
+- spec/fixtures/sample_group.fdoc.meta
+- spec/spec_helper.rb