swagger-docs 0.1.5 → 0.1.6

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,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 67c64b2ae7bcb8d0a653d598dc5f6de70d223d8e
4
- data.tar.gz: 95555f61513a11238944a1e9a4bd361f00e70159
3
+ metadata.gz: 17bc5fa1520eb501616e867896c0f7f7000c31fd
4
+ data.tar.gz: 068f350b226c8fc91d300fce8fd1ac9770ee694e
5
5
  SHA512:
6
- metadata.gz: c047b999407fc51017a1e6ded45582bff68c395446f643d3aaef3f2c3f0c5d397cc6f210c9021348337bce459b5f5e2d88a9eb6ac98814826fd86746b6046f14
7
- data.tar.gz: 2a86f256d2298cb7ab8abadd4e350641bb37da943f77b1dad6f7cb2b1d7106b942b6d55c8efb39636c755464f7fec03a7d20effe3c655b37b96b9aaf2093e0c6
6
+ metadata.gz: 0ea1c7020b0b029f3d897a2c21fb6b72850bb64358d789473ef2bcba346da34e1b730f216435b42f5767742d3bd7e79da19e3c3d38c697402920688e0dc55f0c
7
+ data.tar.gz: a38e70b6f391db69f06676372ffd1dab18ecebc9c042bea9844221ada5bf2196ccf8610e026d73df108e7b43f5b555641a64ca4dad52d4b99036a34abf1a8a49
checksums.yaml.gz.sig CHANGED
Binary file
data/CHANGELOG.md CHANGED
@@ -1,3 +1,11 @@
1
+ ## 0.1.6
2
+
3
+ - Document notes DSL
4
+ - Get rid of unnecessary ternary operator in dsl.rb #54
5
+ - Fix development dependencies gems requirements #53
6
+ - Add support for the `notes` property #52
7
+ - Config's base_api_controller is configurable #51
8
+
1
9
  ## 0.1.5
2
10
  - Delay processing docs DSL to allow changing the context of the controllers #47 @ldnunes
3
11
 
data/README.md CHANGED
@@ -9,6 +9,7 @@ swagger_controller :users, "User Management"
9
9
 
10
10
  swagger_api :index do
11
11
  summary "Fetches all User items"
12
+ notes "This lists all the active users"
12
13
  param :query, :page, :integer, :optional, "Page number"
13
14
  response :unauthorized
14
15
  response :not_acceptable
@@ -83,6 +84,12 @@ The following table shows all the current configuration options and their defaul
83
84
  <td>/</td>
84
85
  </tr>
85
86
 
87
+ <tr>
88
+ <td><b>base_api_controller</b></td>
89
+ <td>The base controller class your project uses; it or its subclasses will be where you call swagger_controller and swagger_api.</td>
90
+ <td>ActionController::Base</td>
91
+ </tr>
92
+
86
93
  <tr>
87
94
  <td><b>clean_directory</b></td>
88
95
  <td>When generating swagger-docs files this option specifies if the api_file_path should be cleaned first. This means that all files will be deleted in the output directory first before any files are generated.</td>
@@ -108,6 +115,7 @@ class Api::V1::UsersController < ApplicationController
108
115
 
109
116
  swagger_api :index do
110
117
  summary "Fetches all User items"
118
+ notes "This lists all the active users"
111
119
  param :query, :page, :integer, :optional, "Page number"
112
120
  param :path, :nested_id, :integer, :optional, "Team Id"
113
121
  response :unauthorized
@@ -163,6 +171,36 @@ class Api::V1::UsersController < ApplicationController
163
171
  end
164
172
  ```
165
173
 
174
+ ### DRYing up common documentation
175
+
176
+ Suppose you have a header or a parameter that must be present on several controllers and methods. Instead of duplicating it on all the controllers you can do this on your API base controller:
177
+
178
+ ```ruby
179
+ class Api::BaseController < ActionController::Base
180
+ class << self
181
+ Swagger::Docs::Generator::set_real_methods
182
+
183
+ def inherited(subclass)
184
+ super
185
+ subclass.class_eval do
186
+ setup_basic_api_documentation
187
+ end
188
+ end
189
+
190
+ private
191
+ def setup_basic_api_documentation
192
+ [:index, :show, :create, :update, :delete].each do |api_action|
193
+ swagger_api api_action do
194
+ param :header, 'Authentication-Token', :string, :required, 'Authentication token'
195
+ end
196
+ end
197
+ end
198
+ end
199
+ end
200
+ ```
201
+
202
+ And then use it as a superclass to all you API controllers. All the subclassed controllers will have the same documentation applied to them.
203
+
166
204
  ### DSL Methods
167
205
 
168
206
  <table>
@@ -179,6 +217,11 @@ end
179
217
  <td>The summary of the API</td>
180
218
  </tr>
181
219
 
220
+ <tr>
221
+ <td>notes (optional)</td>
222
+ <td>The associated notes for the API</td>
223
+ </tr>
224
+
182
225
  <tr>
183
226
  <td>param</td>
184
227
  <td>Standard API Parameter</td>
@@ -216,35 +259,6 @@ https://github.com/richhollis/swagger-docs-sample
216
259
 
217
260
  ### Advanced Customization
218
261
 
219
- #### Recurring parameters
220
-
221
- If you have lots of recurring parameters then you can use this approach suggested by Lucas Dutra Nunes (@ldnunes):
222
-
223
- ```
224
- class Api::BaseController < ActionController::Base
225
- class << self
226
- Swagger::Docs::Generator::set_real_methods
227
-
228
- def inherited(subclass)
229
- super
230
- subclass.class_eval do
231
- setup_basic_api_documentation
232
- end
233
- end
234
-
235
- private
236
-
237
- def setup_basic_api_documentation
238
- [:index, :show, :create, :update, :delete].each do |api_action|
239
- swagger_api api_action do
240
- param :header, 'Authentication-Token', :string, :required, 'Authentication token'
241
- end
242
- end
243
- end
244
- end
245
- end
246
- ```
247
-
248
262
  #### Inheriting from a custom Api controller
249
263
 
250
264
  By default swagger-docs is applied to controllers inheriting from ApplicationController.
@@ -598,6 +612,8 @@ Thanks to jdar, fotinakis, stevschmid, ldnunes and all of our contributors for m
598
612
 
599
613
  ## Contributing
600
614
 
615
+ When raising a Pull Request please ensure that you have provided good test coverage for the request you are making.
616
+
601
617
  1. Fork it
602
618
  2. Create your feature branch (`git checkout -b my-new-feature`)
603
619
  3. Commit your changes (`git commit -am 'Add some feature'`)
@@ -2,15 +2,29 @@ module Swagger
2
2
  module Docs
3
3
  class Config
4
4
  class << self
5
- def base_api_controller; ActionController::Base end
6
- def base_application; Rails.application end
5
+ @@base_api_controller = nil
6
+
7
+ def base_api_controller
8
+ @@base_api_controller || ActionController::Base
9
+ end
10
+
11
+ def base_api_controller=(controller)
12
+ @@base_api_controller = controller
13
+ end
14
+
15
+ def base_application
16
+ Rails.application
17
+ end
18
+
7
19
  def register_apis(versions)
8
20
  base_api_controller.send(:include, ImpotentMethods)
9
21
  @versions = versions
10
22
  end
23
+
11
24
  def registered_apis
12
25
  @versions ||= {}
13
26
  end
27
+
14
28
  def transform_path(path)
15
29
  # This is only for overriding, so don't perform any path transformations by default.
16
30
  path
@@ -16,6 +16,10 @@ module Swagger
16
16
  def summary(text)
17
17
  @summary = text
18
18
  end
19
+
20
+ def notes(text)
21
+ @notes = text
22
+ end
19
23
 
20
24
  def method(method)
21
25
  @method = method
@@ -35,7 +39,7 @@ module Swagger
35
39
 
36
40
  def param(param_type, name, type, required, description = nil, hash={})
37
41
  parameters << {:param_type => param_type, :name => name, :type => type,
38
- :description => description, :required => required == :required ? true : false}.merge(hash)
42
+ :description => description, :required => required == :required}.merge(hash)
39
43
  end
40
44
 
41
45
  # helper method to generate enums
@@ -93,7 +97,7 @@ module Swagger
93
97
  type: type,
94
98
  description: description,
95
99
  }.merge!(hash)
96
- self.required << name if (required == :required ? true : false)
100
+ self.required << name if required == :required
97
101
  end
98
102
  end
99
103
  end
@@ -62,8 +62,7 @@ module Swagger
62
62
  ret = process_path(path, root, config, settings)
63
63
  results[ret[:action]] << ret
64
64
  if ret[:action] == :processed
65
- resource = generate_resource(ret[:path], ret[:apis], ret[:models], settings, root, config)
66
- resources << resource
65
+ resources << generate_resource(ret[:path], ret[:apis], ret[:models], settings, root, config)
67
66
  debased_path = get_debased_path(ret[:path], settings[:controller_base_path])
68
67
  resource_api = {
69
68
  path: "#{Config.transform_path(trim_leading_slash(debased_path))}.{format}",
@@ -1,5 +1,5 @@
1
1
  module Swagger
2
2
  module Docs
3
- VERSION = "0.1.5"
3
+ VERSION = "0.1.6"
4
4
  end
5
5
  end
@@ -40,6 +40,7 @@ module Api
40
40
 
41
41
  swagger_api :update do
42
42
  summary "Updates an existing User"
43
+ notes "Only the given fields are updated."
43
44
  param :path, :id, :integer, :required, "User Id"
44
45
  param :form, :first_name, :string, :optional, "First name"
45
46
  param :form, :last_name, :string, :optional, "Last name"
@@ -0,0 +1,31 @@
1
+ require 'spec_helper'
2
+
3
+ describe Swagger::Docs::Config do
4
+
5
+ require "fixtures/controllers/application_controller"
6
+
7
+ let(:test_controller) { Class.new }
8
+
9
+ before(:each) do
10
+ stub_const('ActionController::Base', ApplicationController)
11
+ end
12
+
13
+ subject { Swagger::Docs::Config }
14
+
15
+ describe "::base_api_controller" do
16
+ it "returns ActionController::Base by default" do
17
+ expect(subject.base_api_controller).to eq(ActionController::Base)
18
+ end
19
+ it "allows assignment of another class" do
20
+ subject.base_api_controller = test_controller
21
+ expect(subject.base_api_controller).to eq(test_controller)
22
+ end
23
+ end
24
+
25
+ describe "::base_application" do
26
+ it "defaults to Rails.application" do
27
+ expect(subject.base_application).to eq (Rails.application)
28
+ end
29
+ end
30
+
31
+ end
@@ -34,7 +34,7 @@ describe Swagger::Docs::Generator do
34
34
  }
35
35
  }
36
36
  before(:each) do
37
- Rails.stub_chain(:application, :routes, :routes).and_return(routes)
37
+ allow(Rails).to receive_message_chain(:application, :routes, :routes).and_return(routes)
38
38
  Swagger::Docs::Generator.set_real_methods
39
39
  require "fixtures/controllers/sample_controller"
40
40
  generate(config)
@@ -83,7 +83,7 @@ describe Swagger::Docs::Generator do
83
83
  })}
84
84
  let(:file_resource) { tmp_dir + 'sample.json' }
85
85
  before(:each) do
86
- Rails.stub_chain(:application, :routes, :routes).and_return(routes)
86
+ allow(Rails).to receive_message_chain(:application, :routes, :routes).and_return(routes)
87
87
  Swagger::Docs::Generator.set_real_methods
88
88
  require "fixtures/controllers/sample_controller"
89
89
  end
@@ -248,7 +248,7 @@ describe Swagger::Docs::Generator do
248
248
  expect(params.first["description"]).to eq "Page number"
249
249
  end
250
250
  it "writes required correctly" do
251
- expect(params.first["required"]).to be_false
251
+ expect(params.first["required"]).to be_falsey
252
252
  end
253
253
  end
254
254
  #"responseMessages":[{"code":401,"message":"Unauthorized"},{"code":406,"message":"Not Acceptable"},{"code":416,"message":"Requested Range Not Satisfiable"}]
@@ -286,6 +286,9 @@ describe Swagger::Docs::Generator do
286
286
  end
287
287
  context "update" do
288
288
  let(:api) { get_api_operation(apis, "sample/{id}", :put) }
289
+ it "writes notes correctly" do
290
+ expect(api["notes"]).to eq "Only the given fields are updated."
291
+ end
289
292
  it "writes model param correctly" do
290
293
  expected_param = {
291
294
  "paramType" => "form",
data/spec/spec_helper.rb CHANGED
@@ -10,7 +10,11 @@ RSpec.configure do |config|
10
10
  config.expect_with :rspec do |c|
11
11
  c.syntax = :expect
12
12
  end
13
- config.color_enabled = true
13
+ config.color = true
14
+
15
+ config.before(:each) do
16
+ Swagger::Docs::Config.base_api_controller = nil # use default object
17
+ end
14
18
  end
15
19
 
16
20
  def generate(config)
data/swagger-docs.gemspec CHANGED
@@ -23,8 +23,8 @@ Gem::Specification.new do |spec|
23
23
  spec.signing_key = File.expand_path("~/.gemcert/gem-private_key.pem") if $0 =~ /gem\z/
24
24
 
25
25
  spec.add_development_dependency "bundler", "~> 1.3"
26
- spec.add_development_dependency "rake", "~> 0"
27
- spec.add_development_dependency "rspec", "~> 0"
28
- spec.add_development_dependency "rails", "~> 0"
29
- spec.add_development_dependency "appraisal", "~> 0"
26
+ spec.add_development_dependency "rake", "~> 10"
27
+ spec.add_development_dependency "rspec", "= 3.0.0beta2"
28
+ spec.add_development_dependency "rails", ">= 3"
29
+ spec.add_development_dependency "appraisal", ">= 1"
30
30
  end
data.tar.gz.sig CHANGED
Binary file
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: swagger-docs
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.5
4
+ version: 0.1.6
5
5
  platform: ruby
6
6
  authors:
7
7
  - Rich Hollis
@@ -30,7 +30,7 @@ cert_chain:
30
30
  RYcsqDfanYBx7QcftOnbeQq7/Ep7Zx+W9+Ph3TiJLMLdAr7bLkgN1SjvrjTL5mQR
31
31
  FuQtYvE4LKiUQpG7vLTRB78dQBlSj9fnv2OM9w==
32
32
  -----END CERTIFICATE-----
33
- date: 2014-04-28 00:00:00.000000000 Z
33
+ date: 2014-05-21 00:00:00.000000000 Z
34
34
  dependencies:
35
35
  - !ruby/object:Gem::Dependency
36
36
  name: bundler
@@ -52,56 +52,56 @@ dependencies:
52
52
  requirements:
53
53
  - - "~>"
54
54
  - !ruby/object:Gem::Version
55
- version: '0'
55
+ version: '10'
56
56
  type: :development
57
57
  prerelease: false
58
58
  version_requirements: !ruby/object:Gem::Requirement
59
59
  requirements:
60
60
  - - "~>"
61
61
  - !ruby/object:Gem::Version
62
- version: '0'
62
+ version: '10'
63
63
  - !ruby/object:Gem::Dependency
64
64
  name: rspec
65
65
  requirement: !ruby/object:Gem::Requirement
66
66
  requirements:
67
- - - "~>"
67
+ - - '='
68
68
  - !ruby/object:Gem::Version
69
- version: '0'
69
+ version: 3.0.0beta2
70
70
  type: :development
71
71
  prerelease: false
72
72
  version_requirements: !ruby/object:Gem::Requirement
73
73
  requirements:
74
- - - "~>"
74
+ - - '='
75
75
  - !ruby/object:Gem::Version
76
- version: '0'
76
+ version: 3.0.0beta2
77
77
  - !ruby/object:Gem::Dependency
78
78
  name: rails
79
79
  requirement: !ruby/object:Gem::Requirement
80
80
  requirements:
81
- - - "~>"
81
+ - - ">="
82
82
  - !ruby/object:Gem::Version
83
- version: '0'
83
+ version: '3'
84
84
  type: :development
85
85
  prerelease: false
86
86
  version_requirements: !ruby/object:Gem::Requirement
87
87
  requirements:
88
- - - "~>"
88
+ - - ">="
89
89
  - !ruby/object:Gem::Version
90
- version: '0'
90
+ version: '3'
91
91
  - !ruby/object:Gem::Dependency
92
92
  name: appraisal
93
93
  requirement: !ruby/object:Gem::Requirement
94
94
  requirements:
95
- - - "~>"
95
+ - - ">="
96
96
  - !ruby/object:Gem::Version
97
- version: '0'
97
+ version: '1'
98
98
  type: :development
99
99
  prerelease: false
100
100
  version_requirements: !ruby/object:Gem::Requirement
101
101
  requirements:
102
- - - "~>"
102
+ - - ">="
103
103
  - !ruby/object:Gem::Version
104
- version: '0'
104
+ version: '1'
105
105
  description: Generates json files for rails apps to use with swagger-ui
106
106
  email:
107
107
  - richhollis@gmail.com
@@ -129,6 +129,7 @@ files:
129
129
  - spec/fixtures/controllers/application_controller.rb
130
130
  - spec/fixtures/controllers/ignored_controller.rb
131
131
  - spec/fixtures/controllers/sample_controller.rb
132
+ - spec/lib/swagger/docs/config_spec.rb
132
133
  - spec/lib/swagger/docs/generator_spec.rb
133
134
  - spec/spec_helper.rb
134
135
  - swagger-docs.gemspec
@@ -161,5 +162,6 @@ test_files:
161
162
  - spec/fixtures/controllers/application_controller.rb
162
163
  - spec/fixtures/controllers/ignored_controller.rb
163
164
  - spec/fixtures/controllers/sample_controller.rb
165
+ - spec/lib/swagger/docs/config_spec.rb
164
166
  - spec/lib/swagger/docs/generator_spec.rb
165
167
  - spec/spec_helper.rb
metadata.gz.sig CHANGED
@@ -1 +1 @@
1
- aS9!fI}ª �@
1
+ ,|�em����}�z�������m��]ȿ8V��3V���A�Z����YE�΅|~�,/_,sOׄ�>�4ۿ��3�}|�S$ը�` 0 �n�Ӷ+��5N[o�"�N%�]6]�túz�}�ݩ�Z\��q�����;ep�2O8$�}������\b� �yLh������3$�B�;��DJ�S��'�"� ��FeCۂ�F������[��n=���o��zQlC_)���η`XA+W� �� W�m�L8c����