fdoc 0.2.6 → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.md CHANGED
@@ -2,9 +2,9 @@
2
2
 
3
3
  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.
4
4
 
5
- In a Rails app, fdoc can help document an API as well as verify that requests and responses adhere to their appropriate schemata.
5
+ In a Rails or Sinatra app, fdoc can help document an API as well as verify that requests and responses adhere to their appropriate schemata.
6
6
 
7
- 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.
7
+ Outside a Rails or Sinatra app, fdoc can provide a common format for API documentation, as well as the ability to generate basic HTML pages for humans to consume.
8
8
 
9
9
  fdoc is short for Farnsdocs. They are named for everybody's favorite, good news-bearing, crotchety old man, Professor Farnsworth.
10
10
 
@@ -51,6 +51,35 @@ fdoc also has a scaffolding mode, where it attemps to infer the schema of a requ
51
51
 
52
52
  For more information on scaffolding, please see the more in-depth [fdoc scaffolding example][github_scaffold].
53
53
 
54
+ ### In a Sinatra app
55
+
56
+ Add fdoc to your Gemfile.
57
+
58
+ gem 'fdoc'
59
+
60
+ 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.
61
+
62
+ ```ruby
63
+ require 'fdoc'
64
+
65
+ Fdoc.service_path = "path/to/your/fdocs"
66
+ ```
67
+
68
+ fdoc is built to work around your Sinatra app specs in rspec, and provides `Fdoc::SpecWatcher` as a mixin. Make sure to include it *inside* your top level describe.
69
+
70
+ ```ruby
71
+ require 'fdoc/spec_watcher'
72
+
73
+ describe Sinatra::Appllication do
74
+ include Rack::Test::Methods
75
+ include Fdoc::SpecWatcher
76
+
77
+ def app
78
+ Sinatra::Application
79
+ end
80
+ end
81
+ ```
82
+
54
83
  ### Outside a Rails App
55
84
 
56
85
  fdoc provides the `fdoc_to_html` script to transform a directory of `.fdoc` files into more human-readable HTML.
@@ -1,5 +1,6 @@
1
1
  require 'erb'
2
2
  require 'kramdown'
3
+ require 'json'
3
4
 
4
5
  # HtmlPresenters assist in generating Html for fdoc classes.
5
6
  # HtmlPresenters is an abstract class with a lot of helper methods
@@ -31,15 +31,23 @@ module Fdoc
31
31
  opts[:fdoc]
32
32
  end
33
33
 
34
+ real_response = if respond_to? :response
35
+ # we are on rails
36
+ response
37
+ else
38
+ # we are on sinatra
39
+ last_response
40
+ end
41
+
34
42
  if path
35
43
  response_params = begin
36
- JSON.parse(response.body)
44
+ JSON.parse(real_response.body)
37
45
  rescue
38
46
  {}
39
47
  end
40
- successful = Fdoc.decide_success(response_params, response.status)
48
+ successful = Fdoc.decide_success(response_params, real_response.status)
41
49
  Service.verify!(verb, path, request_params, response_params,
42
- response.status, successful)
50
+ real_response.status, successful)
43
51
  end
44
52
 
45
53
  result
@@ -3,36 +3,75 @@ require 'spec_helper'
3
3
  require 'fdoc/spec_watcher'
4
4
 
5
5
  describe Fdoc::SpecWatcher do
6
- before do
7
- # This should be an integration test, but for now a smoke test suffices to
8
- # surface obvious bugs and verify some behaviours.
9
- @klass = Class.new do
10
- def example
11
- Struct.new(:metadata).new(:fdoc => 'index')
12
- end
13
6
 
14
- def response
15
- Struct.new(:body, :status).new("{}", 200)
7
+ context "on rails" do
8
+ before do
9
+ # This should be an integration test, but for now a smoke test suffices to
10
+ # surface obvious bugs and verify some behaviours.
11
+ @klass = Class.new do
12
+ def example
13
+ Struct.new(:metadata).new(:fdoc => 'index')
14
+ end
15
+
16
+ def response
17
+ Struct.new(:body, :status).new("{}", 200)
18
+ end
19
+
20
+ def get(action, params)
21
+ params
22
+ end
23
+ end.new
24
+ @klass.extend(Fdoc::SpecWatcher)
25
+ end
26
+
27
+ it 'should verify when params are a hash' do
28
+ Fdoc::Service.should_receive(:verify!).with do |*args|
29
+ args[2] == {:id => 1}
16
30
  end
31
+ @klass.get(:index, {:id => 1})
32
+ end
17
33
 
18
- def get(action, params)
19
- params
34
+ it 'should verify when params are JSON' do
35
+ Fdoc::Service.should_receive(:verify!).with do |*args|
36
+ args[2] == {'id' => 1}
20
37
  end
21
- end.new
22
- @klass.extend(Fdoc::SpecWatcher)
38
+ @klass.get(:index, {:id => 1}.to_json)
39
+ end
23
40
  end
24
41
 
25
- it 'should verify when params are a hash' do
26
- Fdoc::Service.should_receive(:verify!).with do |*args|
27
- args[2] == {:id => 1}
42
+ context "on sinatra" do
43
+
44
+ before do
45
+ # This should be an integration test, but for now a smoke test suffices to
46
+ # surface obvious bugs and verify some behaviours.
47
+ @klass = Class.new do
48
+ def example
49
+ Struct.new(:metadata).new(:fdoc => 'index')
50
+ end
51
+
52
+ def last_response
53
+ Struct.new(:body, :status).new("{}", 200)
54
+ end
55
+
56
+ def get(action, params)
57
+ params
58
+ end
59
+ end.new
60
+ @klass.extend(Fdoc::SpecWatcher)
28
61
  end
29
- @klass.get(:index, {:id => 1})
30
- end
31
62
 
32
- it 'should verify when params are JSON' do
33
- Fdoc::Service.should_receive(:verify!).with do |*args|
34
- args[2] == {'id' => 1}
63
+ it 'should verify when params are a hash' do
64
+ Fdoc::Service.should_receive(:verify!).with do |*args|
65
+ args[2] == {:id => 1}
66
+ end
67
+ @klass.get("/", {:id => 1})
68
+ end
69
+
70
+ it 'should verify when params are JSON' do
71
+ Fdoc::Service.should_receive(:verify!).with do |*args|
72
+ args[2] == {'id' => 1}
73
+ end
74
+ @klass.get("/", {:id => 1}.to_json)
35
75
  end
36
- @klass.get(:index, {:id => 1}.to_json)
37
76
  end
38
77
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: fdoc
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.6
4
+ version: 0.2.7
5
5
  prerelease:
6
6
  platform: ruby
7
7
  authors:
@@ -15,7 +15,7 @@ date: 2011-11-07 00:00:00.000000000 Z
15
15
  dependencies:
16
16
  - !ruby/object:Gem::Dependency
17
17
  name: json
18
- requirement: &70196446801520 !ruby/object:Gem::Requirement
18
+ requirement: &70224688026140 !ruby/object:Gem::Requirement
19
19
  none: false
20
20
  requirements:
21
21
  - - ! '>='
@@ -23,10 +23,10 @@ dependencies:
23
23
  version: '0'
24
24
  type: :runtime
25
25
  prerelease: false
26
- version_requirements: *70196446801520
26
+ version_requirements: *70224688026140
27
27
  - !ruby/object:Gem::Dependency
28
28
  name: json-schema
29
- requirement: &70196446800760 !ruby/object:Gem::Requirement
29
+ requirement: &70224688025480 !ruby/object:Gem::Requirement
30
30
  none: false
31
31
  requirements:
32
32
  - - ! '>='
@@ -34,10 +34,10 @@ dependencies:
34
34
  version: 1.0.1
35
35
  type: :runtime
36
36
  prerelease: false
37
- version_requirements: *70196446800760
37
+ version_requirements: *70224688025480
38
38
  - !ruby/object:Gem::Dependency
39
39
  name: kramdown
40
- requirement: &70196446800080 !ruby/object:Gem::Requirement
40
+ requirement: &70224688024780 !ruby/object:Gem::Requirement
41
41
  none: false
42
42
  requirements:
43
43
  - - ! '>='
@@ -45,10 +45,10 @@ dependencies:
45
45
  version: '0'
46
46
  type: :runtime
47
47
  prerelease: false
48
- version_requirements: *70196446800080
48
+ version_requirements: *70224688024780
49
49
  - !ruby/object:Gem::Dependency
50
50
  name: rake
51
- requirement: &70196446799580 !ruby/object:Gem::Requirement
51
+ requirement: &70224688023900 !ruby/object:Gem::Requirement
52
52
  none: false
53
53
  requirements:
54
54
  - - ! '>='
@@ -56,10 +56,10 @@ dependencies:
56
56
  version: '0'
57
57
  type: :development
58
58
  prerelease: false
59
- version_requirements: *70196446799580
59
+ version_requirements: *70224688023900
60
60
  - !ruby/object:Gem::Dependency
61
61
  name: rspec
62
- requirement: &70196446799040 !ruby/object:Gem::Requirement
62
+ requirement: &70224688023100 !ruby/object:Gem::Requirement
63
63
  none: false
64
64
  requirements:
65
65
  - - ~>
@@ -67,10 +67,10 @@ dependencies:
67
67
  version: '2.5'
68
68
  type: :development
69
69
  prerelease: false
70
- version_requirements: *70196446799040
70
+ version_requirements: *70224688023100
71
71
  - !ruby/object:Gem::Dependency
72
72
  name: nokogiri
73
- requirement: &70196446798560 !ruby/object:Gem::Requirement
73
+ requirement: &70224688022600 !ruby/object:Gem::Requirement
74
74
  none: false
75
75
  requirements:
76
76
  - - ! '>='
@@ -78,10 +78,10 @@ dependencies:
78
78
  version: '0'
79
79
  type: :development
80
80
  prerelease: false
81
- version_requirements: *70196446798560
81
+ version_requirements: *70224688022600
82
82
  - !ruby/object:Gem::Dependency
83
83
  name: cane
84
- requirement: &70196446798060 !ruby/object:Gem::Requirement
84
+ requirement: &70224688022020 !ruby/object:Gem::Requirement
85
85
  none: false
86
86
  requirements:
87
87
  - - ! '>='
@@ -89,7 +89,7 @@ dependencies:
89
89
  version: '0'
90
90
  type: :development
91
91
  prerelease: false
92
- version_requirements: *70196446798060
92
+ version_requirements: *70224688022020
93
93
  description: A tool for documenting API endpoints.
94
94
  email: support@squareup.com
95
95
  executables: