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 +31 -2
- data/lib/fdoc/presenters/html_presenter.rb +1 -0
- data/lib/fdoc/spec_watcher.rb +11 -3
- data/spec/fdoc/spec_watcher_spec.rb +61 -22
- metadata +15 -15
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.
|
data/lib/fdoc/spec_watcher.rb
CHANGED
@@ -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(
|
44
|
+
JSON.parse(real_response.body)
|
37
45
|
rescue
|
38
46
|
{}
|
39
47
|
end
|
40
|
-
successful = Fdoc.decide_success(response_params,
|
48
|
+
successful = Fdoc.decide_success(response_params, real_response.status)
|
41
49
|
Service.verify!(verb, path, request_params, response_params,
|
42
|
-
|
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
|
-
|
15
|
-
|
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
|
-
|
19
|
-
|
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
|
-
|
22
|
-
|
38
|
+
@klass.get(:index, {:id => 1}.to_json)
|
39
|
+
end
|
23
40
|
end
|
24
41
|
|
25
|
-
|
26
|
-
|
27
|
-
|
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
|
-
|
33
|
-
|
34
|
-
|
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.
|
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: &
|
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: *
|
26
|
+
version_requirements: *70224688026140
|
27
27
|
- !ruby/object:Gem::Dependency
|
28
28
|
name: json-schema
|
29
|
-
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: *
|
37
|
+
version_requirements: *70224688025480
|
38
38
|
- !ruby/object:Gem::Dependency
|
39
39
|
name: kramdown
|
40
|
-
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: *
|
48
|
+
version_requirements: *70224688024780
|
49
49
|
- !ruby/object:Gem::Dependency
|
50
50
|
name: rake
|
51
|
-
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: *
|
59
|
+
version_requirements: *70224688023900
|
60
60
|
- !ruby/object:Gem::Dependency
|
61
61
|
name: rspec
|
62
|
-
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: *
|
70
|
+
version_requirements: *70224688023100
|
71
71
|
- !ruby/object:Gem::Dependency
|
72
72
|
name: nokogiri
|
73
|
-
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: *
|
81
|
+
version_requirements: *70224688022600
|
82
82
|
- !ruby/object:Gem::Dependency
|
83
83
|
name: cane
|
84
|
-
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: *
|
92
|
+
version_requirements: *70224688022020
|
93
93
|
description: A tool for documenting API endpoints.
|
94
94
|
email: support@squareup.com
|
95
95
|
executables:
|