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 CHANGED
@@ -1,15 +1,7 @@
1
1
  ---
2
- !binary "U0hBMQ==":
3
- metadata.gz: !binary |-
4
- YmQyODUyY2U2NmY1MDExMjllYWNjOTE2ZTIxYmJiYTdkZTcyM2Q1Mw==
5
- data.tar.gz: !binary |-
6
- ZjUzZjViYWFkYTk0MGVkN2RmNWZlYWIzZjI1NzQ1MDUxNTIzYjA5Nw==
2
+ SHA1:
3
+ metadata.gz: e0c8a26e0663e8e18c42ed476d2dd128e7184c15
4
+ data.tar.gz: 3dc1e0bb361a8f961465147a7d17b380a880a4d8
7
5
  SHA512:
8
- metadata.gz: !binary |-
9
- MjI3MjA3YzM2Njc2MGJkYTY2YzViYjI4YTU1MWZmNDExZjllNDUxYjAyYzJl
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 spec](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md).
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/hide different APIs based on environment.
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
- ## Example (Rails)
30
+ Or install directly with `gem install swagger-blocks`.
33
31
 
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_blocks_spec.rb](https://github.com/fotinakis/swagger-blocks/blob/master/spec/lib/swagger_blocks_spec.rb) file.
32
+ ## Swagger 2.0 example (Rails)
35
33
 
36
- Also note that Rails is not required, you can use Swagger::Blocks with any Ruby web framework.
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
- #### PetsController
36
+ Also note that **Rails is not required**, you can use Swagger::Blocks in plain Ruby objects.
39
37
 
40
- Parameters and features below are defined by the [Swagger 1.2 spec](https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md).
38
+ ### PetsController
41
39
 
42
40
  ```Ruby
43
41
  class PetsController < ActionController::Base
44
42
  include Swagger::Blocks
45
43
 
46
- swagger_api_root :pets do
47
- key :swaggerVersion, '1.2'
48
- key :apiVersion, '1.0.0'
49
- key :basePath, 'http://petstore.swagger.wordnik.com/api'
50
- key :resourcePath, '/pets'
51
- api do
52
- key :path, '/pets/{petId}'
53
- operation do
54
- key :method, 'GET'
55
- key :summary, 'Find pet by ID'
56
- key :notes, 'Returns a pet based on ID'
57
- key :type, :Pet
58
- key :nickname, :getPetById
59
- parameter do
60
- key :paramType, :path
61
- key :name, :petId
62
- key :description, 'ID of pet that needs to be fetched'
63
- key :required, true
64
- key :type, :integer
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
- response_message do
67
- key :code, 400
68
- key :message, 'Invalid ID supplied'
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
- response_message do
71
- key :code, 404
72
- key :message, 'Pet not found'
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
- swagger_model :Pet do
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 :photoUrls do
102
- key :type, :array
103
- items do
104
- key :type, :string
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 :status do
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
- #### Docs controller
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, :show]
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 :swaggerVersion, '1.2'
132
- key :apiVersion, '1.0.0'
220
+ key :swagger, '2.0'
133
221
  info do
134
- key :title, 'Swagger Sample App'
135
- end
136
- api do
137
- key :path, '/pets'
138
- key :description, 'Operations about pets'
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
- Pets,
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 are these lines:
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.build_api_json(params[:id], SWAGGERED_CLASSES)
257
+ render json: Swagger::Blocks.build_root_json(swaggered_classes)
168
258
  ```
169
259
 
170
- 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.
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 [swagger_blocks_spec.rb](https://github.com/fotinakis/swagger-blocks/blob/master/spec/lib/swagger_blocks_spec.rb) for examples of more complex features and declarations possible.
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
- Original idea inspired by **[@richhollis](https://github.com/richhollis/)**'s [swagger-docs](https://github.com/richhollis/swagger-docs/) gem.
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.
@@ -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.