useless-doc 0.1.3 → 0.2.0

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.
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