swagger-blocks 1.0.1 → 1.1
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.
- checksums.yaml +5 -13
- data/README.md +168 -75
- data/README_v1_2.md +141 -0
- data/lib/swagger/blocks.rb +432 -90
- data/lib/swagger/blocks/version.rb +1 -1
- data/spec/lib/swagger_blocks_spec.rb +2 -2
- data/spec/lib/swagger_v2_api_declaration.json +224 -0
- data/spec/lib/swagger_v2_blocks_spec.rb +256 -0
- metadata +21 -16
checksums.yaml
CHANGED
@@ -1,15 +1,7 @@
|
|
1
1
|
---
|
2
|
-
|
3
|
-
metadata.gz:
|
4
|
-
|
5
|
-
data.tar.gz: !binary |-
|
6
|
-
ZjUzZjViYWFkYTk0MGVkN2RmNWZlYWIzZjI1NzQ1MDUxNTIzYjA5Nw==
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: e0c8a26e0663e8e18c42ed476d2dd128e7184c15
|
4
|
+
data.tar.gz: 3dc1e0bb361a8f961465147a7d17b380a880a4d8
|
7
5
|
SHA512:
|
8
|
-
metadata.gz:
|
9
|
-
|
10
|
-
YjRkZjM5NDJhNDIxYzcxZTJkMjRhNGRhMzFjNTNmZjBmZjUzNzg0Y2FkMTMz
|
11
|
-
YzIyODRlODdkM2Y4NWVkY2M0ZjYzNWY1ZjU3ZGI0MWE5MWVmODE=
|
12
|
-
data.tar.gz: !binary |-
|
13
|
-
NjQzZDFhYzllNmUyNDg0NTQ3NzgzYjI0ZTNmODdmMzBjN2I5MDU4NWNiZDEw
|
14
|
-
NDQ4OGJlZTA0MzNlNTdmNjRjMzc0YWZjODIxOWM5Y2VlMzA2NDhmMDczMjE1
|
15
|
-
NjJkZmQ1ZTU3Y2FlM2NmOGIzZGU4MWIwZWY3YmUyMjRjZWUyYjM=
|
6
|
+
metadata.gz: 20d0a772640b989d013bd24571080428811255eb74aa62458341c4bd1ae0641ccbc43fa08f9d9ba4983baf9bbebb9d900b5b88464b6effcacc89d31ba039895b
|
7
|
+
data.tar.gz: e9fe5b2e5e4ac9ac7bd86ec124ae13d1fe2ef076f94b8c9ba6b65f2d6bfbcfad83d93672fe80b0566dd7dc5086ba8a86db9951f35a0cb6b0c987e28cb80dba4a
|
data/README.md
CHANGED
@@ -11,8 +11,8 @@ It helps you write API docs in the [Swagger](https://helloreverb.com/developers/
|
|
11
11
|
|
12
12
|
* Supports **live updating** by design. Change code, refresh your API docs.
|
13
13
|
* **Works with all Ruby web frameworks** including Rails, Sinatra, etc.
|
14
|
-
* **100% support** for all features of the [Swagger 1.2
|
15
|
-
* Flexible—you can use Swagger::Blocks anywhere, split up blocks to fit your style preferences, etc. Since it's pure Ruby and serves definitions dynamically, you can easily use initializers/config objects to change values or even show
|
14
|
+
* **100% support** for all features of the [Swagger 1.2](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md) and [Swagger 2.0](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md) specs.
|
15
|
+
* Flexible—you can use Swagger::Blocks anywhere, split up blocks to fit your style preferences, etc. Since it's pure Ruby and serves definitions dynamically, you can easily use initializers/config objects to change values or even **show different APIs based on environment**.
|
16
16
|
* 1:1 naming with the Swagger spec—block names and nesting should match almost exactly with the swagger spec, with rare exceptions to make things more convenient.
|
17
17
|
|
18
18
|
## Swagger UI demo
|
@@ -26,101 +26,190 @@ http://petstore.swagger.wordnik.com/#!/pet
|
|
26
26
|
Add this line to your application's Gemfile:
|
27
27
|
|
28
28
|
gem 'swagger-blocks'
|
29
|
-
|
30
|
-
Or install directly with `gem install swagger-blocks`.
|
31
29
|
|
32
|
-
|
30
|
+
Or install directly with `gem install swagger-blocks`.
|
33
31
|
|
34
|
-
|
32
|
+
## Swagger 2.0 example (Rails)
|
35
33
|
|
36
|
-
|
34
|
+
This is a simplified example based on the objects in the Petstore [Swagger Sample App](http://petstore.swagger.wordnik.com/#!/pet). For a more complex and complete example, see the [swagger_v2_blocks_spec.rb](https://github.com/fotinakis/swagger-blocks/blob/master/spec/lib/swagger_v2_blocks_spec.rb) file, or see the [v1.2 docs](https://github.com/fotinakis/swagger-blocks/blob/master/README_v1_2.md).
|
37
35
|
|
38
|
-
|
36
|
+
Also note that **Rails is not required**, you can use Swagger::Blocks in plain Ruby objects.
|
39
37
|
|
40
|
-
|
38
|
+
### PetsController
|
41
39
|
|
42
40
|
```Ruby
|
43
41
|
class PetsController < ActionController::Base
|
44
42
|
include Swagger::Blocks
|
45
43
|
|
46
|
-
|
47
|
-
|
48
|
-
|
49
|
-
|
50
|
-
|
51
|
-
|
52
|
-
|
53
|
-
|
54
|
-
key :
|
55
|
-
key :
|
56
|
-
key :
|
57
|
-
|
58
|
-
|
59
|
-
|
60
|
-
|
61
|
-
key :
|
62
|
-
|
63
|
-
|
64
|
-
|
44
|
+
swagger_path '/pets/{id}' do
|
45
|
+
operation :get do
|
46
|
+
key :description, 'Returns a single pet if the user has access'
|
47
|
+
key :operationId, 'findPetById'
|
48
|
+
parameter do
|
49
|
+
key :name, :id
|
50
|
+
key :in, :path
|
51
|
+
key :description, 'ID of pet to fetch'
|
52
|
+
key :required, true
|
53
|
+
key :type, :integer
|
54
|
+
key :format, :int64
|
55
|
+
end
|
56
|
+
response 200 do
|
57
|
+
key :description, 'pet response'
|
58
|
+
schema do
|
59
|
+
key :'$ref', :Pet
|
60
|
+
end
|
61
|
+
end
|
62
|
+
response :default do
|
63
|
+
key :description, 'unexpected error'
|
64
|
+
schema do
|
65
|
+
key :'$ref', :ErrorModel
|
66
|
+
end
|
67
|
+
end
|
68
|
+
end
|
69
|
+
end
|
70
|
+
swagger_path '/pets' do
|
71
|
+
operation :get do
|
72
|
+
key :description, 'Returns all pets from the system that the user has access to'
|
73
|
+
key :operationId, 'findPets'
|
74
|
+
key :produces, [
|
75
|
+
'application/json',
|
76
|
+
'text/html',
|
77
|
+
]
|
78
|
+
parameter do
|
79
|
+
key :name, :tags
|
80
|
+
key :in, :query
|
81
|
+
key :description, 'tags to filter by'
|
82
|
+
key :required, false
|
83
|
+
key :type, :array
|
84
|
+
items do
|
85
|
+
key :type, :string
|
65
86
|
end
|
66
|
-
|
67
|
-
|
68
|
-
|
87
|
+
key :collectionFormat, :csv
|
88
|
+
end
|
89
|
+
parameter do
|
90
|
+
key :name, :limit
|
91
|
+
key :in, :query
|
92
|
+
key :description, 'maximum number of results to return'
|
93
|
+
key :required, false
|
94
|
+
key :type, :integer
|
95
|
+
key :format, :int32
|
96
|
+
end
|
97
|
+
response 200 do
|
98
|
+
key :description, 'pet response'
|
99
|
+
schema do
|
100
|
+
key :type, :array
|
101
|
+
items do
|
102
|
+
key :'$ref', :Pet
|
103
|
+
end
|
69
104
|
end
|
70
|
-
|
71
|
-
|
72
|
-
|
105
|
+
end
|
106
|
+
response :default do
|
107
|
+
key :description, 'unexpected error'
|
108
|
+
schema do
|
109
|
+
key :'$ref', :ErrorModel
|
110
|
+
end
|
111
|
+
end
|
112
|
+
end
|
113
|
+
operation :post do
|
114
|
+
key :description, 'Creates a new pet in the store. Duplicates are allowed'
|
115
|
+
key :operationId, 'addPet'
|
116
|
+
key :produces, [
|
117
|
+
'application/json'
|
118
|
+
]
|
119
|
+
parameter do
|
120
|
+
key :name, :pet
|
121
|
+
key :in, :body
|
122
|
+
key :description, 'Pet to add to the store'
|
123
|
+
key :required, true
|
124
|
+
schema do
|
125
|
+
key :'$ref', :PetInput
|
126
|
+
end
|
127
|
+
end
|
128
|
+
response 200 do
|
129
|
+
key :description, 'pet response'
|
130
|
+
schema do
|
131
|
+
key :'$ref', :Pet
|
132
|
+
end
|
133
|
+
end
|
134
|
+
response :default do
|
135
|
+
key :description, 'unexpected error'
|
136
|
+
schema do
|
137
|
+
key :'$ref', :ErrorModel
|
73
138
|
end
|
74
139
|
end
|
75
140
|
end
|
76
141
|
end
|
77
|
-
|
142
|
+
|
78
143
|
# ...
|
79
144
|
end
|
80
145
|
```
|
81
146
|
|
147
|
+
### Models
|
148
|
+
|
82
149
|
#### Pet model
|
83
150
|
|
84
151
|
```Ruby
|
85
152
|
class Pet < ActiveRecord::Base
|
86
153
|
include Swagger::Blocks
|
87
154
|
|
88
|
-
|
89
|
-
key :id, :Pet
|
155
|
+
swagger_schema :Pet do
|
90
156
|
key :required, [:id, :name]
|
91
157
|
property :id do
|
92
158
|
key :type, :integer
|
93
159
|
key :format, :int64
|
94
|
-
key :description, 'unique identifier for the pet'
|
95
|
-
key :minimum, '0.0'
|
96
|
-
key :maximum, '100.0'
|
97
160
|
end
|
98
161
|
property :name do
|
99
162
|
key :type, :string
|
100
163
|
end
|
101
|
-
property :
|
102
|
-
key :type, :
|
103
|
-
|
104
|
-
|
164
|
+
property :tag do
|
165
|
+
key :type, :string
|
166
|
+
end
|
167
|
+
end
|
168
|
+
|
169
|
+
swagger_schema :PetInput do
|
170
|
+
allOf do
|
171
|
+
schema do
|
172
|
+
key :'$ref', :Pet
|
105
173
|
end
|
174
|
+
schema do
|
175
|
+
key :required, [:name]
|
176
|
+
property :id do
|
177
|
+
key :type, :integer
|
178
|
+
key :format, :int64
|
179
|
+
end
|
180
|
+
end
|
181
|
+
end
|
182
|
+
end
|
183
|
+
|
184
|
+
# ...
|
185
|
+
end
|
186
|
+
```
|
187
|
+
|
188
|
+
#### Error model
|
189
|
+
|
190
|
+
``` Ruby
|
191
|
+
class ErrorModel # Notice, this is just a plain ruby object.
|
192
|
+
include Swagger::Blocks
|
193
|
+
|
194
|
+
swagger_schema :ErrorModel do
|
195
|
+
key :required, [:code, :message]
|
196
|
+
property :code do
|
197
|
+
key :type, :integer
|
198
|
+
key :format, :int32
|
106
199
|
end
|
107
|
-
property :
|
200
|
+
property :message do
|
108
201
|
key :type, :string
|
109
|
-
key :description, 'pet status in the store'
|
110
|
-
key :enum, [:available, :pending, :sold]
|
111
202
|
end
|
112
203
|
end
|
113
|
-
|
114
|
-
# ...
|
115
204
|
end
|
116
205
|
```
|
117
206
|
|
118
|
-
|
207
|
+
### Docs controller
|
119
208
|
|
120
209
|
To integrate these definitions with Swagger UI, we need a docs controller that can serve the JSON definitions.
|
121
210
|
|
122
211
|
```Ruby
|
123
|
-
resources :apidocs, only: [:index
|
212
|
+
resources :apidocs, only: [:index]
|
124
213
|
```
|
125
214
|
|
126
215
|
```Ruby
|
@@ -128,52 +217,53 @@ class ApidocsController < ActionController::Base
|
|
128
217
|
include Swagger::Blocks
|
129
218
|
|
130
219
|
swagger_root do
|
131
|
-
key :
|
132
|
-
key :apiVersion, '1.0.0'
|
220
|
+
key :swagger, '2.0'
|
133
221
|
info do
|
134
|
-
key :
|
135
|
-
|
136
|
-
|
137
|
-
|
138
|
-
key :
|
222
|
+
key :version, '1.0.0'
|
223
|
+
key :title, 'Swagger Petstore'
|
224
|
+
key :description, 'A sample API that uses a petstore as an example to ' \
|
225
|
+
'demonstrate features in the swagger-2.0 specification'
|
226
|
+
key :termsOfService, 'http://helloreverb.com/terms/'
|
227
|
+
contact do
|
228
|
+
key :name, 'Wordnik API Team'
|
229
|
+
end
|
230
|
+
license do
|
231
|
+
key :name, 'MIT'
|
232
|
+
end
|
139
233
|
end
|
234
|
+
key :host, 'petstore.swagger.wordnik.com'
|
235
|
+
key :basePath, '/api'
|
236
|
+
key :consumes, ['application/json']
|
237
|
+
key :produces, ['application/json']
|
140
238
|
end
|
141
|
-
|
239
|
+
|
142
240
|
# A list of all classes that have swagger_* declarations.
|
143
241
|
SWAGGERED_CLASSES = [
|
144
242
|
PetsController,
|
145
|
-
|
243
|
+
Pet,
|
244
|
+
ErrorModel,
|
146
245
|
self,
|
147
246
|
].freeze
|
148
|
-
|
247
|
+
|
149
248
|
def index
|
150
249
|
render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
|
151
250
|
end
|
152
|
-
|
153
|
-
def show
|
154
|
-
render json: Swagger::Blocks.build_api_json(params[:id], SWAGGERED_CLASSES)
|
155
|
-
end
|
156
251
|
end
|
157
|
-
|
158
252
|
```
|
159
253
|
|
160
|
-
The special part of this controller
|
161
|
-
|
162
|
-
```Ruby
|
163
|
-
render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
|
164
|
-
```
|
254
|
+
The special part of this controller is this line:
|
165
255
|
|
166
256
|
```Ruby
|
167
|
-
render json: Swagger::Blocks.
|
257
|
+
render json: Swagger::Blocks.build_root_json(swaggered_classes)
|
168
258
|
```
|
169
259
|
|
170
|
-
|
260
|
+
That is the only line necessary to build the full [root Swagger object](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schema) JSON and all definitions underneath it. You simply pass in a list of all the "swaggered" classes in your app.
|
171
261
|
|
172
262
|
Now, simply point Swagger UI at `/apidocs` and everything should Just Work™. If you change any of the Swagger block definitions, you can simply refresh Swagger UI to see the changes.
|
173
263
|
|
174
264
|
## Reference
|
175
265
|
|
176
|
-
See the [
|
266
|
+
See the [swagger_v2_blocks_spec.rb](https://github.com/fotinakis/swagger-blocks/blob/master/spec/lib/swagger_v2_blocks_spec.rb) for examples of more complex features and declarations possible.
|
177
267
|
|
178
268
|
## Contributing
|
179
269
|
|
@@ -185,9 +275,12 @@ See the [swagger_blocks_spec.rb](https://github.com/fotinakis/swagger-blocks/blo
|
|
185
275
|
|
186
276
|
## Release notes
|
187
277
|
|
278
|
+
* v1.1: Support for Swagger 2.0 spec.
|
188
279
|
* v1.0.1: Make backwards-compatible with Ruby 1.9.3.
|
189
280
|
* v1.0.0: Initial major release.
|
190
281
|
|
191
282
|
## Credits
|
192
283
|
|
193
|
-
|
284
|
+
Thanks to [@ali-graham](https://github.com/ali-graham) for contributing support for Swagger 2.0.
|
285
|
+
|
286
|
+
Original idea inspired by [@richhollis](https://github.com/richhollis/)'s [swagger-docs](https://github.com/richhollis/swagger-docs/) gem.
|
data/README_v1_2.md
ADDED
@@ -0,0 +1,141 @@
|
|
1
|
+
# Swagger 1.2 example (Rails)
|
2
|
+
|
3
|
+
This is a simplified example based on the objects in the Petstore [Swagger Sample App](http://petstore.swagger.wordnik.com/#!/pet). For a more complex and complete example, see the [swagger_blocks_spec.rb](https://github.com/fotinakis/swagger-blocks/blob/master/spec/lib/swagger_blocks_spec.rb) file.
|
4
|
+
|
5
|
+
Also note that Rails is not required, you can use Swagger::Blocks with any Ruby web framework.
|
6
|
+
|
7
|
+
### PetsController
|
8
|
+
|
9
|
+
Parameters and features below are defined by the [Swagger 1.2 spec](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md).
|
10
|
+
|
11
|
+
```Ruby
|
12
|
+
class PetsController < ActionController::Base
|
13
|
+
include Swagger::Blocks
|
14
|
+
|
15
|
+
swagger_api_root :pets do
|
16
|
+
key :swaggerVersion, '1.2'
|
17
|
+
key :apiVersion, '1.0.0'
|
18
|
+
key :basePath, 'http://petstore.swagger.wordnik.com/api'
|
19
|
+
key :resourcePath, '/pets'
|
20
|
+
api do
|
21
|
+
key :path, '/pets/{petId}'
|
22
|
+
operation do
|
23
|
+
key :method, 'GET'
|
24
|
+
key :summary, 'Find pet by ID'
|
25
|
+
key :notes, 'Returns a pet based on ID'
|
26
|
+
key :type, :Pet
|
27
|
+
key :nickname, :getPetById
|
28
|
+
parameter do
|
29
|
+
key :paramType, :path
|
30
|
+
key :name, :petId
|
31
|
+
key :description, 'ID of pet that needs to be fetched'
|
32
|
+
key :required, true
|
33
|
+
key :type, :integer
|
34
|
+
end
|
35
|
+
response_message do
|
36
|
+
key :code, 400
|
37
|
+
key :message, 'Invalid ID supplied'
|
38
|
+
end
|
39
|
+
response_message do
|
40
|
+
key :code, 404
|
41
|
+
key :message, 'Pet not found'
|
42
|
+
end
|
43
|
+
end
|
44
|
+
end
|
45
|
+
end
|
46
|
+
|
47
|
+
# ...
|
48
|
+
end
|
49
|
+
```
|
50
|
+
|
51
|
+
### Pet model
|
52
|
+
|
53
|
+
```Ruby
|
54
|
+
class Pet < ActiveRecord::Base
|
55
|
+
include Swagger::Blocks
|
56
|
+
|
57
|
+
swagger_model :Pet do
|
58
|
+
key :id, :Pet
|
59
|
+
key :required, [:id, :name]
|
60
|
+
property :id do
|
61
|
+
key :type, :integer
|
62
|
+
key :format, :int64
|
63
|
+
key :description, 'unique identifier for the pet'
|
64
|
+
key :minimum, '0.0'
|
65
|
+
key :maximum, '100.0'
|
66
|
+
end
|
67
|
+
property :name do
|
68
|
+
key :type, :string
|
69
|
+
end
|
70
|
+
property :photoUrls do
|
71
|
+
key :type, :array
|
72
|
+
items do
|
73
|
+
key :type, :string
|
74
|
+
end
|
75
|
+
end
|
76
|
+
property :status do
|
77
|
+
key :type, :string
|
78
|
+
key :description, 'pet status in the store'
|
79
|
+
key :enum, [:available, :pending, :sold]
|
80
|
+
end
|
81
|
+
end
|
82
|
+
|
83
|
+
# ...
|
84
|
+
end
|
85
|
+
```
|
86
|
+
|
87
|
+
### Docs controller
|
88
|
+
|
89
|
+
To integrate these definitions with Swagger UI, we need a docs controller that can serve the JSON definitions.
|
90
|
+
|
91
|
+
```Ruby
|
92
|
+
resources :apidocs, only: [:index, :show]
|
93
|
+
```
|
94
|
+
|
95
|
+
```Ruby
|
96
|
+
class ApidocsController < ActionController::Base
|
97
|
+
include Swagger::Blocks
|
98
|
+
|
99
|
+
swagger_root do
|
100
|
+
key :swaggerVersion, '1.2'
|
101
|
+
key :apiVersion, '1.0.0'
|
102
|
+
info do
|
103
|
+
key :title, 'Swagger Sample App'
|
104
|
+
end
|
105
|
+
api do
|
106
|
+
key :path, '/pets'
|
107
|
+
key :description, 'Operations about pets'
|
108
|
+
end
|
109
|
+
end
|
110
|
+
|
111
|
+
# A list of all classes that have swagger_* declarations.
|
112
|
+
SWAGGERED_CLASSES = [
|
113
|
+
PetsController,
|
114
|
+
Pets,
|
115
|
+
self,
|
116
|
+
].freeze
|
117
|
+
|
118
|
+
def index
|
119
|
+
render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
|
120
|
+
end
|
121
|
+
|
122
|
+
def show
|
123
|
+
render json: Swagger::Blocks.build_api_json(params[:id], SWAGGERED_CLASSES)
|
124
|
+
end
|
125
|
+
end
|
126
|
+
|
127
|
+
```
|
128
|
+
|
129
|
+
The special part of this controller are these lines:
|
130
|
+
|
131
|
+
```Ruby
|
132
|
+
render json: Swagger::Blocks.build_root_json(SWAGGERED_CLASSES)
|
133
|
+
```
|
134
|
+
|
135
|
+
```Ruby
|
136
|
+
render json: Swagger::Blocks.build_api_json(params[:id], SWAGGERED_CLASSES)
|
137
|
+
```
|
138
|
+
|
139
|
+
Those are the only lines necessary to build the root Swagger [Resource Listing](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#51-resource-listing) JSON and the JSON for each Swagger [API Declaration](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#52-api-declaration). You simply pass in a list of all the "swaggered" classes in your app.
|
140
|
+
|
141
|
+
Now, simply point Swagger UI at `/apidocs` and everything should Just Work™. If you change any of the Swagger block definitions, you can simply refresh Swagger UI to see the changes.
|