swaggard 0.5.1 → 0.5.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +65 -60
- data/lib/swaggard/engine.rb +4 -3
- data/lib/swaggard/swagger/operation.rb +14 -5
- data/lib/swaggard/swagger/parameters/body.rb +1 -1
- data/lib/swaggard/swagger/property.rb +1 -1
- data/lib/swaggard/swagger/response.rb +69 -34
- data/lib/swaggard/version.rb +1 -1
- data/lib/swaggard.rb +2 -0
- metadata +2 -3
- data/lib/swaggard/swagger/default_response.rb +0 -17
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: fb687a1c23c74e8d1e4ba9c61ee2cf721825dd5e
|
4
|
+
data.tar.gz: e5ce9def3e2218ab2de5aed5464cb3c58444845d
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: e080901eb5706ca5f0a878a7c820281b0ee88a69e6f7b37f1a7b8cffc1cdee25ddbdba5778d24df0713b51d8ee035631f5aba64db68a12b6f25c2e8124d8d14c
|
7
|
+
data.tar.gz: 36d8dd883ecebd67b634e0cc13bac4fbae700b67eef630628d46f538d4f2be1f0332b1e72f4ff940b3fc09360df69032a0842d30b70b08f0be2f133f50528cab
|
data/README.md
CHANGED
@@ -1,41 +1,25 @@
|
|
1
|
-
Swaggard
|
2
|
-
========
|
1
|
+
# Swaggard
|
3
2
|
|
4
3
|
Swaggard is a Rails Engine that can be used to document a REST api. It does this by generating a json that is compliant with [Swagger](http://swagger.io) and displaying it using [Swagger-ui](https://github.com/wordnik/swagger-ui).
|
5
4
|
This gem is inspired and based on [SwaggerYard](https://github.com/synctv/swagger_yard) by [Chris Trinh](https://github.com/chtrinh).
|
6
5
|
|
7
|
-
Compatibility
|
8
|
-
-------------
|
9
|
-
This table tracks the version of Swagger UI used on each Swaggard version and
|
10
|
-
the supported rails version.
|
11
|
-
|
12
|
-
Swaggard Version | Swagger UI Version | Supported Rails Versions
|
13
|
-
---------------- | -------------------| ------------------------
|
14
|
-
0.5.0 | 2.2.8 | 4 - 5
|
15
|
-
0.4.0 | 2.2.8 | 4
|
16
|
-
0.3.0 | 2.1.3 | 4
|
17
|
-
0.2.1 | 2.1.3 | 4
|
18
|
-
0.2.0 | 2.1.3 | 4
|
19
|
-
0.1.1 | 2.1.3 | 4
|
20
|
-
0.1.0 | 2.1.3 | 4
|
21
|
-
0.0.4 | 2.1.8-M1 | 4
|
22
6
|
|
23
|
-
|
24
|
-
-----------------------
|
7
|
+
## Compatibility
|
25
8
|
|
26
|
-
|
27
|
-
|
9
|
+
This table tracks the version of Swagger UI used on each Swaggard version and
|
10
|
+
the supported rails version.
|
28
11
|
|
29
|
-
|
30
|
-
|
31
|
-
|
32
|
-
|
33
|
-
|
34
|
-
|
12
|
+
Swaggard Version | Swagger UI Version | Supported Rails Versions
|
13
|
+
---------------- | ------------------- | ------------------------
|
14
|
+
0.5.x | 2.2.8 | 4 - 5
|
15
|
+
0.4.x | 2.2.8 | 4
|
16
|
+
0.3.x | 2.1.3 | 4
|
17
|
+
0.2.x | 2.1.3 | 4
|
18
|
+
0.1.x | 2.1.3 | 4
|
19
|
+
0.0.x | 2.1.8-M1 | 4
|
35
20
|
|
36
21
|
|
37
|
-
Installation
|
38
|
-
------------
|
22
|
+
## Installation
|
39
23
|
|
40
24
|
Put Swaggard in your Gemfile:
|
41
25
|
|
@@ -46,8 +30,7 @@ Install the gem with Bundler:
|
|
46
30
|
bundle install
|
47
31
|
|
48
32
|
|
49
|
-
Getting Started
|
50
|
-
-----------------
|
33
|
+
## Getting Started
|
51
34
|
|
52
35
|
Place your configuration in a your rails initializers
|
53
36
|
|
@@ -74,8 +57,8 @@ Access the raw swagger json
|
|
74
57
|
|
75
58
|
open http://localhost:3000/swagger.json
|
76
59
|
|
77
|
-
|
78
|
-
|
60
|
+
|
61
|
+
## Example
|
79
62
|
|
80
63
|
By just using Swaggard you'll get documentation for the endpoints that exist on your service:
|
81
64
|
http method, path, path params. And grouping will be done based on the controller that holds
|
@@ -86,15 +69,23 @@ of the expected inputs and outputs or even change the grouping of the endpoints.
|
|
86
69
|
|
87
70
|
Here is a example of how to use Swaggard
|
88
71
|
|
72
|
+
# config/routes.rb
|
73
|
+
|
74
|
+
resources :users, only: [] do
|
75
|
+
resources :posts, controller: 'users/posts', only: [:index, :create]
|
76
|
+
end
|
77
|
+
|
78
|
+
|
89
79
|
# app/controllers/users/posts_controller.rb
|
90
80
|
|
91
|
-
#
|
92
|
-
#
|
81
|
+
# @tag UsersPosts
|
93
82
|
# API for creating, deleting, and listing user posts.
|
94
|
-
class
|
83
|
+
class Users::PostsController < ActionController::Base
|
95
84
|
|
96
85
|
# Returns the list of user posts
|
97
86
|
#
|
87
|
+
# @response_status 201
|
88
|
+
# @response_root posts
|
98
89
|
# @response_class Array<PostSerializer>
|
99
90
|
def index
|
100
91
|
...
|
@@ -155,10 +146,26 @@ Will generate
|
|
155
146
|
![Web UI](https://raw.githubusercontent.com/Moove-it/swaggard/master/example/web-ui.png)
|
156
147
|
|
157
148
|
|
158
|
-
|
159
|
-
|
160
|
-
|
161
|
-
|
149
|
+
## Available tags
|
150
|
+
|
151
|
+
### Controllers
|
152
|
+
|
153
|
+
- `@tag name` This is used to indicate under what `name` tag this controller needs to be grouped. If not provided it will use the full controller class name.
|
154
|
+
- `@query_parameter [type] name` This is used to indicate that your action receives the `name` parameter of `type` on the query string.
|
155
|
+
- `@body_parameter [type] name` This is used to indicate that your action receives the `name` parameter of `type` on the body.
|
156
|
+
- `@response_class type` This is used to indicate that your action returns a response of `type`.
|
157
|
+
- `@response_status 200` This is used to indicate the response code of your action when everything goes well.
|
158
|
+
- `@response_root name` This is used to indicate that your action returns its response inside a root key element `name`. If not provided the root is omitted and the response its returned directly.
|
159
|
+
- `@form_parameter`
|
160
|
+
- `@parameter_list`
|
161
|
+
|
162
|
+
### Models
|
163
|
+
|
164
|
+
- `@attr [type] name` This is used to indicate that your models has an attribute `name` of `type`.
|
165
|
+
|
166
|
+
## Primitives
|
167
|
+
|
168
|
+
When one of these types is given Swaggard will handle them directly instead of searching for a definition:
|
162
169
|
|
163
170
|
- integer
|
164
171
|
- long
|
@@ -173,8 +180,8 @@ a definition:
|
|
173
180
|
- password
|
174
181
|
- hash
|
175
182
|
|
176
|
-
|
177
|
-
|
183
|
+
|
184
|
+
## Authentication
|
178
185
|
|
179
186
|
Swaggard supports two types of authentication: header and query.
|
180
187
|
|
@@ -189,8 +196,8 @@ You can configure it as follows:
|
|
189
196
|
|
190
197
|
Even if you provide a authentication_value you can later change it from the ui.
|
191
198
|
|
192
|
-
|
193
|
-
|
199
|
+
|
200
|
+
## Access authorization
|
194
201
|
|
195
202
|
Swaggard supports access authorization.
|
196
203
|
|
@@ -205,8 +212,7 @@ You can configure it as follows:
|
|
205
212
|
If you not set `access_username`, everyone will have access to Swagger documentation.
|
206
213
|
|
207
214
|
|
208
|
-
Additional parameters
|
209
|
-
--------------
|
215
|
+
## Additional parameters
|
210
216
|
|
211
217
|
Swaggard supports additional parameters to be sent on every request, either as a header or as part of the query.
|
212
218
|
|
@@ -221,8 +227,8 @@ type can be 'header' or 'query'.
|
|
221
227
|
If value is provided then it will be used as a default.
|
222
228
|
You can change/set the value for the parameters in the ui.
|
223
229
|
|
224
|
-
|
225
|
-
|
230
|
+
|
231
|
+
## Default content type
|
226
232
|
|
227
233
|
You can set default content type in Swaggard configuration as follows:
|
228
234
|
|
@@ -233,8 +239,8 @@ You can set default content type in Swaggard configuration as follows:
|
|
233
239
|
|
234
240
|
If you set `default_content_type`, Swagger will use it in example request.
|
235
241
|
|
236
|
-
|
237
|
-
|
242
|
+
|
243
|
+
## Language
|
238
244
|
|
239
245
|
You can set the language for SwaggerUI as follows:
|
240
246
|
|
@@ -260,8 +266,8 @@ Supported values are:
|
|
260
266
|
- tr
|
261
267
|
- zh-cn
|
262
268
|
|
263
|
-
|
264
|
-
|
269
|
+
|
270
|
+
## Caching
|
265
271
|
|
266
272
|
You can improve Swagger performance by using caching. You can enable `use_cache` in Swaggard configuration as follows:
|
267
273
|
|
@@ -274,8 +280,9 @@ If you set `use_cache` as `Rails.env.production?`, Swagger will use cache only i
|
|
274
280
|
|
275
281
|
Note. For cache clearing you can execute `rake swaggard:clear_cache`.
|
276
282
|
|
277
|
-
|
278
|
-
|
283
|
+
|
284
|
+
## Documentation Scoping
|
285
|
+
|
279
286
|
Its possible to only generate Swagger documentation for a subset of your application controllers
|
280
287
|
to do this you just need to use the `controllers_path` config option.
|
281
288
|
For instance to only generate documentation for the controllers under `app/controllers/api` you
|
@@ -290,22 +297,20 @@ need do this:
|
|
290
297
|
|
291
298
|
The default value for `controllers_path` is `"#{Rails.root}/app/controllers/**/*.rb"`.
|
292
299
|
|
293
|
-
|
294
|
-
|
300
|
+
|
301
|
+
## More Information
|
295
302
|
|
296
303
|
- [Swagger](http://swagger.io)
|
297
304
|
- [Swagger-ui](https://github.com/wordnik/swagger-ui)
|
298
305
|
- [Yard](https://github.com/lsegal/yard)
|
299
306
|
|
300
307
|
|
301
|
-
Author
|
302
|
-
------
|
308
|
+
## Author
|
303
309
|
|
304
310
|
[Adrian Gomez](https://github.com/adrian-gomez)
|
305
311
|
|
306
312
|
|
307
|
-
Credits
|
308
|
-
-------
|
313
|
+
## Credits
|
309
314
|
|
310
315
|
[Chris Trinh](https://github.com/chtrinh) author of [SwaggerYard](https://github.com/synctv/swagger_yard) in which this gem is
|
311
316
|
inspired and used a base.
|
data/lib/swaggard/engine.rb
CHANGED
@@ -1,8 +1,9 @@
|
|
1
1
|
unless Rails::Application.instance_methods.include?(:assets_manifest)
|
2
2
|
warn <<-END
|
3
|
-
[Swaggard] It seems you are using an api only rails setup but swaggard
|
4
|
-
[Swaggard] neeeds sprockets in order to work
|
5
|
-
[Swaggard]
|
3
|
+
[Swaggard] It seems you are using an api only rails setup, but swaggard
|
4
|
+
[Swaggard] neeeds sprockets in order to work so its going to require it.
|
5
|
+
[Swaggard] This might have undesired side effects, if thats not the case
|
6
|
+
[Swaggard] you can ignore this warning.
|
6
7
|
END
|
7
8
|
require 'sprockets/railtie'
|
8
9
|
end
|
@@ -5,7 +5,6 @@ require_relative 'parameters/path'
|
|
5
5
|
require_relative 'parameters/query'
|
6
6
|
|
7
7
|
require_relative 'response'
|
8
|
-
require_relative 'default_response'
|
9
8
|
|
10
9
|
module Swaggard
|
11
10
|
module Swagger
|
@@ -37,7 +36,11 @@ module Swaggard
|
|
37
36
|
when 'parameter_list'
|
38
37
|
@parameters << Parameters::List.new(value)
|
39
38
|
when 'response_class'
|
40
|
-
|
39
|
+
success_response.response_class = value
|
40
|
+
when 'response_status'
|
41
|
+
success_response.status_code = value
|
42
|
+
when 'response_root'
|
43
|
+
success_response.response_root = value
|
41
44
|
end
|
42
45
|
end
|
43
46
|
|
@@ -45,7 +48,7 @@ module Swaggard
|
|
45
48
|
|
46
49
|
@parameters.sort_by { |parameter| parameter.name }
|
47
50
|
|
48
|
-
@responses <<
|
51
|
+
@responses << success_response
|
49
52
|
end
|
50
53
|
|
51
54
|
def valid?
|
@@ -69,11 +72,17 @@ module Swaggard
|
|
69
72
|
end
|
70
73
|
|
71
74
|
def definitions
|
72
|
-
@
|
75
|
+
@responses.map(&:definition).compact.tap do |definitions|
|
76
|
+
definitions << @body_parameter.definition if @body_parameter
|
77
|
+
end
|
73
78
|
end
|
74
79
|
|
75
80
|
private
|
76
81
|
|
82
|
+
def success_response
|
83
|
+
@success_response ||= Response.new("#{@tag.controller_class.to_s}.#{@name}")
|
84
|
+
end
|
85
|
+
|
77
86
|
def body_parameter
|
78
87
|
return @body_parameter if @body_parameter
|
79
88
|
|
@@ -98,4 +107,4 @@ module Swaggard
|
|
98
107
|
|
99
108
|
end
|
100
109
|
end
|
101
|
-
end
|
110
|
+
end
|
@@ -2,52 +2,87 @@ module Swaggard
|
|
2
2
|
module Swagger
|
3
3
|
class Response
|
4
4
|
|
5
|
-
|
5
|
+
DEFAULT_STATUS_CODE = 'default'
|
6
|
+
DEFAULT_DESCRIPTION = 'successful operation'
|
7
|
+
PRIMITIVE_TYPES = %w[integer long float double string byte binary boolean date date-time password hash]
|
6
8
|
|
7
|
-
|
9
|
+
attr_writer :status_code, :description
|
8
10
|
|
9
|
-
def initialize(
|
10
|
-
@
|
11
|
-
|
11
|
+
def initialize(operation_name)
|
12
|
+
@operation_name = operation_name
|
13
|
+
@response_model = ResponseModel.new
|
14
|
+
end
|
15
|
+
|
16
|
+
def definition
|
17
|
+
return unless @response_root.present?
|
18
|
+
|
19
|
+
@definition ||= Definition.new("#{@operation_name}_response").tap do |definition|
|
20
|
+
definition.add_property(@response_model)
|
21
|
+
end
|
22
|
+
end
|
23
|
+
|
24
|
+
def status_code
|
25
|
+
@status_code || DEFAULT_STATUS_CODE
|
26
|
+
end
|
27
|
+
|
28
|
+
def response_class=(value)
|
29
|
+
@response_model.parse(value)
|
30
|
+
end
|
31
|
+
|
32
|
+
def response_root=(root)
|
33
|
+
@response_root = root
|
34
|
+
@response_model.id = root
|
35
|
+
end
|
36
|
+
|
37
|
+
def description
|
38
|
+
@description || DEFAULT_DESCRIPTION
|
12
39
|
end
|
13
40
|
|
14
41
|
def to_doc
|
15
|
-
{
|
16
|
-
|
17
|
-
|
18
|
-
|
42
|
+
{ 'description' => description }.tap do |doc|
|
43
|
+
schema = if @response_root.present?
|
44
|
+
{ '$ref' => "#/definitions/#{definition.id}" }
|
45
|
+
elsif @response_model.response_class.present?
|
46
|
+
@response_model.to_doc
|
47
|
+
end
|
48
|
+
|
49
|
+
doc.merge!('schema' => schema) if schema
|
50
|
+
end
|
19
51
|
end
|
20
52
|
|
21
53
|
private
|
22
54
|
|
23
|
-
|
24
|
-
|
25
|
-
|
26
|
-
|
27
|
-
|
28
|
-
|
29
|
-
|
30
|
-
|
31
|
-
|
32
|
-
|
33
|
-
if @is_array_response
|
34
|
-
{
|
35
|
-
'type' => 'array',
|
36
|
-
'items' => response_class_type
|
37
|
-
}
|
38
|
-
else
|
39
|
-
response_class_type
|
55
|
+
class ResponseModel
|
56
|
+
attr_accessor :id, :response_class
|
57
|
+
|
58
|
+
def parse(value)
|
59
|
+
@is_array_response = value =~ /Array/
|
60
|
+
@response_class = if @is_array_response
|
61
|
+
value.match(/^Array<(.*)>$/)[1]
|
62
|
+
else
|
63
|
+
value
|
64
|
+
end
|
40
65
|
end
|
41
|
-
end
|
42
66
|
|
43
|
-
|
44
|
-
|
45
|
-
|
46
|
-
|
47
|
-
|
67
|
+
def to_doc
|
68
|
+
if @is_array_response
|
69
|
+
{
|
70
|
+
'type' => 'array',
|
71
|
+
'items' => response_class_type
|
72
|
+
}
|
73
|
+
else
|
74
|
+
response_class_type
|
75
|
+
end
|
48
76
|
end
|
49
|
-
end
|
50
77
|
|
78
|
+
def response_class_type
|
79
|
+
if PRIMITIVE_TYPES.include?(@response_class)
|
80
|
+
{ 'type' => @response_class }
|
81
|
+
else
|
82
|
+
{ '$ref' => "#/definitions/#@response_class" }
|
83
|
+
end
|
84
|
+
end
|
85
|
+
end
|
51
86
|
end
|
52
87
|
end
|
53
|
-
end
|
88
|
+
end
|
data/lib/swaggard/version.rb
CHANGED
data/lib/swaggard.rb
CHANGED
@@ -28,6 +28,8 @@ module Swaggard
|
|
28
28
|
::YARD::Tags::Library.define_tag('Body parameter', :body_parameter)
|
29
29
|
::YARD::Tags::Library.define_tag('Parameter list', :parameter_list)
|
30
30
|
::YARD::Tags::Library.define_tag('Response class', :response_class)
|
31
|
+
::YARD::Tags::Library.define_tag('Response Root', :response_root)
|
32
|
+
::YARD::Tags::Library.define_tag('Response Status', :response_status)
|
31
33
|
end
|
32
34
|
|
33
35
|
def get_doc(host)
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: swaggard
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.5.
|
4
|
+
version: 0.5.2
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Adrian Gomez
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2017-
|
11
|
+
date: 2017-02-08 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: rails
|
@@ -167,7 +167,6 @@ files:
|
|
167
167
|
- lib/swaggard/parsers/controllers.rb
|
168
168
|
- lib/swaggard/parsers/models.rb
|
169
169
|
- lib/swaggard/parsers/routes.rb
|
170
|
-
- lib/swaggard/swagger/default_response.rb
|
171
170
|
- lib/swaggard/swagger/definition.rb
|
172
171
|
- lib/swaggard/swagger/operation.rb
|
173
172
|
- lib/swaggard/swagger/parameters/base.rb
|