useless-doc 0.1.3 → 0.2.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (27) hide show
  1. data/lib/useless/doc/core/body.rb +60 -0
  2. data/lib/useless/doc/core/header.rb +26 -0
  3. data/lib/useless/doc/core/request.rb +106 -0
  4. data/lib/useless/doc/core/resource.rb +32 -0
  5. data/lib/useless/doc/{response/status.rb → core/response.rb} +13 -5
  6. data/lib/useless/doc/dsl.rb +41 -53
  7. data/lib/useless/doc/rack/proxy.rb +1 -2
  8. data/lib/useless/doc/rack/retriever.rb +2 -0
  9. data/lib/useless/doc/serialization/dump.rb +8 -15
  10. data/lib/useless/doc/serialization/load.rb +30 -57
  11. data/lib/useless/doc/ui/godel/template.mustache +84 -111
  12. data/lib/useless/doc/ui/godel.rb +12 -30
  13. data/lib/useless/doc/ui.rb +1 -1
  14. data/lib/useless/doc/version.rb +1 -1
  15. data/spec/documents/twonk.json +76 -85
  16. data/spec/useless/doc/dsl_spec.rb +19 -30
  17. data/spec/useless/doc/serialization/dump_spec.rb +40 -42
  18. data/spec/useless/doc/serialization/load_spec.rb +50 -52
  19. data/spec/useless/doc/sinatra_spec.rb +11 -15
  20. metadata +7 -10
  21. data/lib/useless/doc/action.rb +0 -50
  22. data/lib/useless/doc/body.rb +0 -58
  23. data/lib/useless/doc/header.rb +0 -24
  24. data/lib/useless/doc/request/parameter.rb +0 -47
  25. data/lib/useless/doc/request.rb +0 -29
  26. data/lib/useless/doc/resource.rb +0 -29
  27. data/lib/useless/doc/response.rb +0 -29
data/lib/useless/doc/ui/godel/template.mustache CHANGED
@@ -10,7 +10,7 @@
10
10
 
11
11
  <p>{{description}}</p>
12
12
 
13
- {{#actions}}
13
+ {{#requests}}
14
14
  <section>
15
15
  <h2>{{method}}</h2>
16
16
 
@@ -20,121 +20,94 @@
20
20
  <li>{{authentication_requirement}}</li>
21
21
  </ul>
22
22
 
23
- {{#request}}
23
+ {{#parameters?}}
24
24
  <section>
25
- <h3>Request</h3>
26
-
27
- {{#parameters?}}
28
- <section>
29
- <h4>Parameters</h4>
30
- <table>
31
- <th>
32
- <tr>
33
- <td>Name</td>
34
- <td>Type</td>
35
- <td>Required</td>
36
- <td>Default</td>
37
- <td>Description</td>
38
- <tr>
39
- </th>
40
- <tbody>
41
- {{#parameters}}
42
- <tr>
43
- <td>{{key}}</td>
44
- <td>{{type}}</td>
45
- <td>{{required}}</td>
46
- <td>{{default}}</td>
47
- <td>{{description}}</td>
48
- </tr>
49
- {{/parameters}}
50
- </tbody>
51
- </table>
52
- </section>
53
- {{/parameters?}}
54
-
55
- {{#headers?}}
56
- <section>
57
- <h4>Headers</h4>
58
- <table>
59
- <th>
60
- <tr>
61
- <td>Name</td>
62
- <td>Description</td>
63
- <tr>
64
- </th>
65
- <tbody>
66
- {{#headers}}
67
- <tr>
68
- <td>{{key}}</td>
69
- <td>{{description}}</td>
70
- </tr>
71
- {{/headers}}
72
- </tbody>
73
- </table>
74
- </section>
75
- {{/headers?}}
76
-
77
- {{#body}}
78
- <section>
79
- <h4>Body</h4>
80
-
81
- <ul>
82
- <li>{{content_type}}</li>
83
- </ul>
25
+ <h4>Parameters</h4>
26
+ <table>
27
+ <th>
28
+ <tr>
29
+ <td>Name</td>
30
+ <td>Type</td>
31
+ <td>Required</td>
32
+ <td>Default</td>
33
+ <td>Description</td>
34
+ <tr>
35
+ </th>
36
+ <tbody>
37
+ {{#parameters}}
38
+ <tr>
39
+ <td>{{key}}</td>
40
+ <td>{{type}}</td>
41
+ <td>{{required}}</td>
42
+ <td>{{default}}</td>
43
+ <td>{{description}}</td>
44
+ </tr>
45
+ {{/parameters}}
46
+ </tbody>
47
+ </table>
48
+ </section>
49
+ {{/parameters?}}
84
50
 
85
- <table>
86
- <th>
87
- <tr>
88
- <td>Name</td>
89
- <td>Type</td>
90
- <td>Required</td>
91
- <td>Default</td>
92
- <td>Description</td>
93
- <tr>
94
- </th>
95
- <tbody>
96
- {{#attributes}}
97
- <tr>
98
- <td>{{key}}</td>
99
- <td>{{type}}</td>
100
- <td>{{required}}</td>
101
- <td>{{default}}</td>
102
- <td>{{description}}</td>
103
- </tr>
104
- {{/attributes}}
105
- </tbody>
106
- </table>
107
- </section>
108
- {{/body}}
51
+ {{#headers?}}
52
+ <section>
53
+ <h4>Headers</h4>
54
+ <table>
55
+ <th>
56
+ <tr>
57
+ <td>Name</td>
58
+ <td>Description</td>
59
+ <tr>
60
+ </th>
61
+ <tbody>
62
+ {{#headers}}
63
+ <tr>
64
+ <td>{{key}}</td>
65
+ <td>{{description}}</td>
66
+ </tr>
67
+ {{/headers}}
68
+ </tbody>
69
+ </table>
70
+ </section>
71
+ {{/headers?}}
109
72
 
73
+ {{#body}}
74
+ <section>
75
+ <h4>Body</h4>
76
+
77
+ <ul>
78
+ <li>{{content_type}}</li>
79
+ </ul>
80
+
81
+ <table>
82
+ <th>
83
+ <tr>
84
+ <td>Name</td>
85
+ <td>Type</td>
86
+ <td>Required</td>
87
+ <td>Default</td>
88
+ <td>Description</td>
89
+ <tr>
90
+ </th>
91
+ <tbody>
92
+ {{#attributes}}
93
+ <tr>
94
+ <td>{{key}}</td>
95
+ <td>{{type}}</td>
96
+ <td>{{required}}</td>
97
+ <td>{{default}}</td>
98
+ <td>{{description}}</td>
99
+ </tr>
100
+ {{/attributes}}
101
+ </tbody>
102
+ </table>
110
103
  </section>
111
- {{/request}}
104
+ {{/body}}
112
105
 
113
- {{#response}}
106
+ {{#responses}}
114
107
  <section>
115
- <h3>Response</h3>
108
+ <h3>{{code}}</h3>
116
109
 
117
- {{#statuses?}}
118
- <section>
119
- <h4>Statuses</h4>
120
- <table>
121
- <th>
122
- <tr>
123
- <td>Code</td>
124
- <td>Description</td>
125
- <tr>
126
- </th>
127
- <tbody>
128
- {{#statuses}}
129
- <tr>
130
- <td>{{code}}</td>
131
- <td>{{description}}</td>
132
- </tr>
133
- {{/statuses}}
134
- </tbody>
135
- </table>
136
- </section>
137
- {{/statuses?}}
110
+ <p>{{description}}</p>
138
111
 
139
112
  {{#headers?}}
140
113
  <section>
@@ -192,8 +165,8 @@
192
165
  {{/body}}
193
166
 
194
167
  </section>
195
- {{/response}}
168
+ {{/responses}}
196
169
  </section>
197
- {{/actions}}
170
+ {{/requests}}
198
171
 
199
172
  </body>
data/lib/useless/doc/ui/godel.rb CHANGED
@@ -22,44 +22,26 @@ module Useless
22
22
  @resource = resource
23
23
  end
24
24
 
25
- def actions
26
- @resource.actions.map{ |action| Godel::Action.new(action) }
25
+ def requests
26
+ @resource.requests.map{ |request| Godel::Request.new(request) }
27
27
  end
28
28
  end
29
29
 
30
- class Action
30
+ class Request
31
31
  extend Forwardable
32
32
 
33
- def_delegators :@action, :description, :method
33
+ def_delegators :@request, :method, :description, :parameters, :headers, :body
34
34
 
35
- def initialize(action)
36
- @action = action
35
+ def initialize(request)
36
+ @request = request
37
37
  end
38
38
 
39
39
  def authentication_requirement
40
- @action.authentication_required ?
40
+ @request.authentication_required ?
41
41
  'Authentication Required' :
42
42
  'Authenication Not Required'
43
43
  end
44
44
 
45
- def request
46
- Godel::Request.new(@action.request)
47
- end
48
-
49
- def response
50
- Godel::Response.new(@action.response)
51
- end
52
- end
53
-
54
- class Request
55
- extend Forwardable
56
-
57
- def_delegators :@request, :parameters, :headers, :body
58
-
59
- def initialize(request)
60
- @request = request
61
- end
62
-
63
45
  def parameters?
64
46
  parameters.any?
65
47
  end
@@ -67,21 +49,21 @@ module Useless
67
49
  def headers?
68
50
  headers.any?
69
51
  end
52
+
53
+ def responses
54
+ @request.responses.map { |response| Godel::Response.new(response) }
55
+ end
70
56
  end
71
57
 
72
58
  class Response
73
59
  extend Forwardable
74
60
 
75
- def_delegators :@response, :statuses, :headers, :body
61
+ def_delegators :@response, :code, :description, :headers, :body
76
62
 
77
63
  def initialize(response)
78
64
  @response = response
79
65
  end
80
66
 
81
- def statuses?
82
- statuses.any?
83
- end
84
-
85
67
  def headers?
86
68
  headers.any?
87
69
  end
data/lib/useless/doc/ui.rb CHANGED
@@ -10,7 +10,7 @@ module Useless
10
10
  self.template_file = dir + 'template.mustache'
11
11
 
12
12
  extend Forwardable
13
- def_delegators :@resource, :path, :description, :actions
13
+ def_delegators :@resource, :path, :description, :requests
14
14
  end
15
15
  end
16
16
 
data/lib/useless/doc/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  module Useless
2
2
  module Doc
3
- VERSION = '0.1.3'
3
+ VERSION = '0.2.0'
4
4
  end
5
5
  end
data/spec/documents/twonk.json CHANGED
@@ -1,106 +1,97 @@
1
1
  {
2
2
  "path": "/twonks/:id",
3
3
  "description": "The most critical aspect.",
4
- "actions": [
4
+ "requests": [
5
5
  {
6
- "description": "Retrieve a representation of an individual twonk.",
7
6
  "method": "GET",
7
+ "description": "Retrieve a representation of an individual twonk.",
8
8
  "authentication_required": false,
9
- "request": {
10
- "parameters": [
11
- {
12
- "type": "path",
13
- "key": "id",
14
- "required": true,
15
- "description": "The ID of the desired twonk."
16
- },
17
- {
18
- "type": "query",
19
- "key": "werp",
20
- "required": false,
21
- "default": 12,
22
- "description": "Self-explanatory."
23
- }
24
- ],
25
- "headers": [
26
- {
27
- "key": "User-Agent",
28
- "description": "The thingy you're using."
29
- }
30
- ]
31
- },
32
- "response": {
33
- "statuses": [
34
- {
35
- "code": 200,
36
- "description": "The specified twonk was retrieved successfully."
37
- },
38
- {
39
- "code": 404,
40
- "description": "A twonk with the specified ID could not be found."
9
+ "parameters": [
10
+ {
11
+ "type": "path",
12
+ "key": "id",
13
+ "required": true,
14
+ "description": "The ID of the desired twonk."
15
+ },
16
+ {
17
+ "type": "query",
18
+ "key": "werp",
19
+ "required": false,
20
+ "default": 12,
21
+ "description": "Self-explanatory."
22
+ }
23
+ ],
24
+ "headers": [
25
+ {
26
+ "key": "User-Agent",
27
+ "description": "The thingy you're using."
28
+ }
29
+ ],
30
+ "responses": [
31
+ {
32
+ "code": 404,
33
+ "description": "A twonk with the specified ID could not be found."
34
+ },
35
+ {
36
+ "code": 200,
37
+ "description": "The specified twonk was retrieved successfully.",
38
+ "body": {
39
+ "content_type": "application/json",
40
+ "attributes": [
41
+ {
42
+ "key": "name",
43
+ "type": "string",
44
+ "required": true,
45
+ "description": "The name of the twonk."
46
+ },
47
+ {
48
+ "key": "created_by",
49
+ "type": "object",
50
+ "required": true,
51
+ "description": "The short name of the user who created the twonk."
52
+ }
53
+ ]
41
54
  }
42
- ],
43
- "body": {
44
- "content_type": "application/json",
45
- "attributes": [
46
- {
47
- "key": "name",
48
- "type": "string",
49
- "required": true,
50
- "description": "The name of the twonk."
51
- },
52
- {
53
- "key": "created_by",
54
- "type": "object",
55
- "required": true,
56
- "description": "The short name of the user who created the twonk."
57
- }
58
- ]
59
55
  }
60
-
61
- }
56
+ ]
62
57
  },
63
58
 
64
59
  {
65
- "description": "Update a twonk.",
66
60
  "method": "PUT",
61
+ "description": "Update a twonk.",
67
62
  "authentication_required": true,
68
- "request": {
69
- "parameters": [
63
+ "parameters": [
64
+ {
65
+ "type": "path",
66
+ "key": "id",
67
+ "required": true,
68
+ "description": "The ID of the twonk to be updated."
69
+ }
70
+ ],
71
+ "body": {
72
+ "content_type": "application/x-www-form-urlencoded",
73
+ "attributes": [
70
74
  {
71
- "type": "path",
72
- "key": "id",
75
+ "key": "name",
76
+ "type": "string",
73
77
  "required": true,
74
- "description": "The ID of the twonk to be updated."
75
- }
76
- ],
77
- "body": {
78
- "content_type": "application/x-www-form-urlencoded",
79
- "attributes": [
80
- {
81
- "key": "name",
82
- "type": "string",
83
- "required": true,
84
- "description": "The name of the twonk."
85
- },
86
- {
87
- "key": "hoinked_by",
88
- "type": "number",
89
- "required": false,
90
- "default": 3,
91
- "description": "The ID of the person who hoinked this twonk."
92
- }
93
- ]
94
- }
95
- },
96
- "response": {
97
- "statuses": [
78
+ "description": "The name of the twonk."
79
+ },
98
80
  {
99
- "code": 201,
100
- "description": "The specified twonk was updated successfully."
81
+ "key": "hoinked_by",
82
+ "type": "number",
83
+ "required": false,
84
+ "default": 3,
85
+ "description": "The ID of the person who hoinked this twonk."
101
86
  }
102
87
  ]
103
- }
88
+ },
89
+ "responses": [
90
+ {
91
+ "code": 201,
92
+ "description": "The specified twonk was updated successfully."
93
+ }
94
+ ]
104
95
  }
105
96
  ]
106
97
  }
data/spec/useless/doc/dsl_spec.rb CHANGED
@@ -12,18 +12,12 @@ describe Useless::Doc::DSL do
12
12
 
13
13
  get 'Returns a full listing of the collection' do
14
14
  authentication_required false
15
+ parameter 'page', 'The page of widgets that you\'d like',
16
+ type: :query, required: false, default: 1
17
+ header 'X-Twiddle', 'The twiddle threshold.'
15
18
 
16
- request do
17
- parameter 'page', 'The page of widgets that you\'d like',
18
- type: :query, required: false, default: 1
19
-
20
- header 'X-Twiddle', 'The twiddle threshold.'
21
- end
22
-
23
- response do
24
- status 200, 'The widgets were appropriately returned'
25
- status 404, 'All the widgets are gone!!!!!'
26
-
19
+ response 404, 'All the widgets are gone!!!!!'
20
+ response 200, 'The widgets were appropriately returned' do
27
21
  header 'X-Twonk', 'The twonk coefficient.'
28
22
 
29
23
  body do
@@ -38,34 +32,29 @@ describe Useless::Doc::DSL do
38
32
 
39
33
  post do
40
34
  authentication_required true
41
-
42
35
  description 'Creates a new widget'
43
36
 
44
- request do
45
- body do
46
- content_type 'application/json'
37
+ body do
38
+ content_type 'application/json'
47
39
 
48
- attribute 'name', 'The name of the widget', required: true
49
- attribute 'age', 'The age of the widget', type: :number, required: false, default: 42
50
- end
40
+ attribute 'name', 'The name of the widget', required: true
41
+ attribute 'age', 'The age of the widget', type: :number, required: false, default: 42
51
42
  end
52
43
 
53
- response do
54
- status 201, 'The widget was successfully created'
55
- status 422, 'The widget couldn\'t be created because name was missing'
56
- end
44
+ response 201, 'The widget was successfully created'
45
+ response 422, 'The widget couldn\'t be created because name was missing'
57
46
  end
58
47
  end
59
48
 
60
49
  resource.description.should == 'The entire collection of widgets'
61
- resource.actions[0].method.should == 'GET'
62
- resource.actions[0].request.headers[0].description.should == 'The twiddle threshold.'
63
- resource.actions[0].response.statuses[0].code.should == 200
64
- resource.actions[1].method.should == 'POST'
65
- resource.actions[1].description.should == 'Creates a new widget'
66
- resource.actions[1].request.body.content_type.should == 'application/json'
67
- resource.actions[1].request.body.attributes[0].key.should == 'name'
68
- resource.actions[1].response.statuses[1].description.should == 'The widget couldn\'t be created because name was missing'
50
+ resource.requests[0].method.should == 'GET'
51
+ resource.requests[0].headers[0].description.should == 'The twiddle threshold.'
52
+ resource.requests[0].responses[1].code.should == 200
53
+ resource.requests[1].method.should == 'POST'
54
+ resource.requests[1].description.should == 'Creates a new widget'
55
+ resource.requests[1].body.content_type.should == 'application/json'
56
+ resource.requests[1].body.attributes[0].key.should == 'name'
57
+ resource.requests[1].responses[1].description.should == 'The widget couldn\'t be created because name was missing'
69
58
  end
70
59
  end
71
60
  end