grape-swagger 0.10.1 → 0.10.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.rubocop_todo.yml +10 -10
- data/.travis.yml +4 -1
- data/CHANGELOG.md +89 -65
- data/CONTRIBUTING.md +8 -8
- data/Gemfile +1 -1
- data/README.md +90 -16
- data/RELEASING.md +1 -1
- data/UPGRADING.md +20 -3
- data/grape-swagger.gemspec +1 -1
- data/lib/grape-swagger.rb +49 -476
- data/lib/grape-swagger/doc_methods.rb +495 -0
- data/lib/grape-swagger/version.rb +1 -1
- data/spec/api_description_spec.rb +2 -2
- data/spec/api_global_models_spec.rb +21 -21
- data/spec/api_models_spec.rb +62 -42
- data/spec/api_paths_spec.rb +64 -0
- data/spec/api_with_standalone_namespace_spec.rb +16 -16
- data/spec/array_entity_spec.rb +34 -0
- data/spec/array_params_spec.rb +35 -6
- data/spec/default_api_spec.rb +42 -0
- data/spec/float_api_spec.rb +1 -1
- data/spec/grape-swagger_helper_spec.rb +14 -1
- data/spec/mounted_target_class_spec.rb +63 -0
- data/spec/non_default_api_spec.rb +47 -16
- data/spec/param_type_spec.rb +52 -0
- data/spec/param_values_spec.rb +130 -0
- data/spec/reference_entity.rb +80 -0
- data/spec/simple_mounted_api_spec.rb +2 -2
- data/spec/support/grape_version.rb +11 -0
- metadata +50 -40
- data/.ruby-version +0 -1
- data/spec/range_values_spec.rb +0 -49
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 5a6996205661a00c64c62bb85fe5c68ea79c0acf
|
|
4
|
+
data.tar.gz: 446c20aa4754161e0fee6aaff5894af24ec06f76
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 4968dde338ad1282e6100ec9d7b318c76267346f9048d01d8027065fa7e1e7468ff80038448ebf5184d809512c9b8dbaa5584f7996085b63ed76b5092a7de45c
|
|
7
|
+
data.tar.gz: 468c21cc9341a54105c7c892432b9e2818b4811bb3add16047b847cac8d6be45beaddfa8b6b41bd08087333b46f1c90317583cf43c3b276cdec1f4b185fdec54
|
data/.rubocop_todo.yml
CHANGED
|
@@ -1,42 +1,42 @@
|
|
|
1
1
|
# This configuration was generated by `rubocop --auto-gen-config`
|
|
2
|
-
# on 2015-
|
|
2
|
+
# on 2015-04-01 08:13:45 -0400 using RuboCop version 0.27.0.
|
|
3
3
|
# The point is for the user to remove these configuration records
|
|
4
4
|
# one by one as the offenses are removed from the code base.
|
|
5
5
|
# Note that changes in the inspected code, or installation of new
|
|
6
6
|
# versions of RuboCop, may require this file to be generated again.
|
|
7
7
|
|
|
8
|
-
# Offense count:
|
|
8
|
+
# Offense count: 11
|
|
9
9
|
Metrics/AbcSize:
|
|
10
|
-
Max:
|
|
10
|
+
Max: 360
|
|
11
11
|
|
|
12
12
|
# Offense count: 1
|
|
13
13
|
# Configuration parameters: CountComments.
|
|
14
14
|
Metrics/ClassLength:
|
|
15
|
-
Max:
|
|
15
|
+
Max: 509
|
|
16
16
|
|
|
17
17
|
# Offense count: 6
|
|
18
18
|
Metrics/CyclomaticComplexity:
|
|
19
|
-
Max:
|
|
19
|
+
Max: 102
|
|
20
20
|
|
|
21
|
-
# Offense count:
|
|
21
|
+
# Offense count: 312
|
|
22
22
|
# Configuration parameters: AllowURI, URISchemes.
|
|
23
23
|
Metrics/LineLength:
|
|
24
24
|
Max: 254
|
|
25
25
|
|
|
26
|
-
# Offense count:
|
|
26
|
+
# Offense count: 21
|
|
27
27
|
# Configuration parameters: CountComments.
|
|
28
28
|
Metrics/MethodLength:
|
|
29
|
-
Max:
|
|
29
|
+
Max: 381
|
|
30
30
|
|
|
31
31
|
# Offense count: 5
|
|
32
32
|
Metrics/PerceivedComplexity:
|
|
33
|
-
Max:
|
|
33
|
+
Max: 105
|
|
34
34
|
|
|
35
35
|
# Offense count: 8
|
|
36
36
|
Style/ClassVars:
|
|
37
37
|
Enabled: false
|
|
38
38
|
|
|
39
|
-
# Offense count:
|
|
39
|
+
# Offense count: 81
|
|
40
40
|
Style/Documentation:
|
|
41
41
|
Enabled: false
|
|
42
42
|
|
data/.travis.yml
CHANGED
|
@@ -3,9 +3,9 @@ language: ruby
|
|
|
3
3
|
sudo: false
|
|
4
4
|
|
|
5
5
|
rvm:
|
|
6
|
+
- 2.2.2
|
|
6
7
|
- 2.1.1
|
|
7
8
|
- 2.0.0
|
|
8
|
-
- 1.9.3
|
|
9
9
|
- rbx-2.2.10
|
|
10
10
|
- jruby-19mode
|
|
11
11
|
|
|
@@ -14,4 +14,7 @@ env:
|
|
|
14
14
|
- GRAPE_VERSION=0.9.0
|
|
15
15
|
- GRAPE_VERSION=0.10.0
|
|
16
16
|
- GRAPE_VERSION=0.10.1
|
|
17
|
+
- GRAPE_VERSION=0.11.0
|
|
18
|
+
- GRAPE_VERSION=0.12.0
|
|
19
|
+
- GRAPE_VERSION=0.13.0
|
|
17
20
|
- GRAPE_VERSION=HEAD
|
data/CHANGELOG.md
CHANGED
|
@@ -1,98 +1,122 @@
|
|
|
1
|
+
### 0.10.2 (August 19, 2015)
|
|
2
|
+
|
|
3
|
+
#### Features
|
|
4
|
+
|
|
5
|
+
* [#215](https://github.com/ruby-grape/grape-swagger/pull/223): Support swagger `defaultValue` without the need to set a Grape `default` - [@jv-dan](https://github.com/jv-dan).
|
|
6
|
+
|
|
7
|
+
#### Fixes
|
|
8
|
+
|
|
9
|
+
* [#273](https://github.com/ruby-grape/grape-swagger/pull/273): Fix for hide_format when API class uses a single format with Grape 0.12.0 - [@mattolson](https://github.com/mattolson).
|
|
10
|
+
* [#264](https://github.com/ruby-grape/grape-swagger/pull/264): Consistent header param types - [@QuickPay](https://github.com/QuickPay).
|
|
11
|
+
* [#260](https://github.com/ruby-grape/grape-swagger/pull/260), [#261](https://github.com/ruby-grape/grape-swagger/pull/261): Fixed endpoints that would wrongly be hidden if `hide_documentation_path` is set - [@QuickPay](https://github.com/QuickPay).
|
|
12
|
+
* [#259](https://github.com/ruby-grape/grape-swagger/pull/259): Fixed range values and converting integer :values range to a minimum/maximum numeric Range - [@u2](https://github.com/u2).
|
|
13
|
+
* [#252](https://github.com/ruby-grape/grape-swagger/pull/252): Allow docs to mounted in separate class than target - [@iangreenleaf](https://github.com/iangreenleaf).
|
|
14
|
+
* [#251](https://github.com/ruby-grape/grape-swagger/pull/251): Fixed model id equal to model name when root existing in entities - [@aitortomas](https://github.com/aitortomas).
|
|
15
|
+
* [#232](https://github.com/ruby-grape/grape-swagger/pull/232): Fixed missing raw array params - [@u2](https://github.com/u2).
|
|
16
|
+
* [#234](https://github.com/ruby-grape/grape-swagger/pull/234): Fixed range :values with float - [@azhi](https://github.com/azhi).
|
|
17
|
+
* [#225](https://github.com/ruby-grape/grape-swagger/pull/225): Fixed `param_type` to have it read from parameter's documentation hash - [@zsxking](https://github.com/zsxking).
|
|
18
|
+
* [#235](https://github.com/ruby-grape/grape-swagger/pull/235): Fixed nested entity names in parameters and as `$ref` in models - [@frodrigo](https://github.com/frodrigo).
|
|
19
|
+
* [#206](https://github.com/ruby-grape/grape-swagger/pull/206): Fixed 'is_array' in the return entity being ignored - [@igormoochnick](https://github.com/igormoochnick).
|
|
20
|
+
* [#266](https://github.com/ruby-grape/grape-swagger/pull/266): Respect primitive mapping on type and format attributes of 1.2 swagger spec - [@frodrigo](https://github.com/frodrigo).
|
|
21
|
+
* [#268](https://github.com/ruby-grape/grape-swagger/pull/268): Fixed handling of `type: Array[...]` - [@frodrigo](https://github.com/frodrigo).
|
|
22
|
+
* [#284](https://github.com/ruby-grape/grape-swagger/pull/284): Use new params syntax for swagger doc endpoint, fix an issue that `:name` params not recognized by `declared` method - [@calfzhou](https://github.com/calfzhou).
|
|
23
|
+
* [#286](https://github.com/ruby-grape/grape-swagger/pull/286): Use `detail` value for `notes` - fix an issue where `detail` value specified in a block passed to `desc` was ignored - [@rngtng](https://github.com/rngtng).
|
|
24
|
+
|
|
1
25
|
### 0.10.1 (March 11, 2015)
|
|
2
26
|
|
|
3
|
-
* [#227](https://github.com/
|
|
4
|
-
* [#226](https://github.com/
|
|
27
|
+
* [#227](https://github.com/ruby-grape/grape-swagger/issues/227): Fix: nested routes under prefix not documented - [@dblock](https://github.com/dblock).
|
|
28
|
+
* [#226](https://github.com/ruby-grape/grape-swagger/issues/226): Fix: be defensive with nil exposure types - [@dblock](https://github.com/dblock).
|
|
5
29
|
|
|
6
30
|
### 0.10.0 (March 10, 2015)
|
|
7
31
|
|
|
8
32
|
#### Features
|
|
9
33
|
|
|
10
|
-
* [#217](https://github.com/
|
|
11
|
-
* [#214](https://github.com/
|
|
12
|
-
* [#196](https://github.com/
|
|
13
|
-
* [#200](https://github.com/
|
|
14
|
-
* [#207](https://github.com/
|
|
15
|
-
* [#220](https://github.com/
|
|
34
|
+
* [#217](https://github.com/ruby-grape/grape-swagger/pull/217): Support Array of entities for proper rendering of grape-entity input dependencies - [@swistaczek](https://github.com/swistaczek).
|
|
35
|
+
* [#214](https://github.com/ruby-grape/grape-swagger/pull/214): Allow anything that responds to `call` to be used in `:hidden` - [@zbelzer](https://github.com/zbelzer).
|
|
36
|
+
* [#196](https://github.com/ruby-grape/grape-swagger/pull/196): If `:type` is omitted, see if it's available in `:using` - [@jhollinger](https://github.com/jhollinger).
|
|
37
|
+
* [#200](https://github.com/ruby-grape/grape-swagger/pull/200): Treat `type: Symbol` as string form parameter - [@ypresto](https://github.com/ypresto).
|
|
38
|
+
* [#207](https://github.com/ruby-grape/grape-swagger/pull/207): Support grape `mutually_exclusive` - [@mintuhouse](https://github.com/mintuhouse).
|
|
39
|
+
* [#220](https://github.com/ruby-grape/grape-swagger/pull/220): Support standalone appearance of namespace routes with a custom name instead of forced nesting - [@croeck](https://github.com/croeck).
|
|
16
40
|
|
|
17
41
|
#### Fixes
|
|
18
42
|
|
|
19
|
-
* [#221](https://github.com/
|
|
20
|
-
* [#211](https://github.com/
|
|
21
|
-
* [#210](https://github.com/
|
|
22
|
-
* [#208](https://github.com/
|
|
23
|
-
* [#216](https://github.com/
|
|
43
|
+
* [#221](https://github.com/ruby-grape/grape-swagger/pull/221): Fixed group parameters' name with type Array - [@u2](https://github.com/u2).
|
|
44
|
+
* [#211](https://github.com/ruby-grape/grape-swagger/pull/211): Fixed the dependency, just `require 'grape'` - [@u2](https://github.com/u2).
|
|
45
|
+
* [#210](https://github.com/ruby-grape/grape-swagger/pull/210): Fixed the range `:values` option, now exposed as `enum` parameters - [@u2](https://github.com/u2).
|
|
46
|
+
* [#208](https://github.com/ruby-grape/grape-swagger/pull/208): Fixed `Float` parameters, exposed as Swagger `float` types - [@u2](https://github.com/u2).
|
|
47
|
+
* [#216](https://github.com/ruby-grape/grape-swagger/pull/216), [#192](https://github.com/ruby-grape/grape-swagger/issues/192), [#189](https://github.com/ruby-grape/grape-swagger/issues/189): Fixed API route paths matching for root endpoints with `grape ~> 0.10.0`, specific `format` and `:path` versioning - [@dm1try](https://github.com/dm1try), [@minch](https://github.com/minch).
|
|
24
48
|
|
|
25
49
|
### 0.9.0 (December 19, 2014)
|
|
26
50
|
|
|
27
|
-
* [#91](https://github.com/
|
|
28
|
-
* [#154](https://github.com/
|
|
29
|
-
* [#162](https://github.com/
|
|
30
|
-
* [#169](https://github.com/
|
|
31
|
-
* [#166](https://github.com/
|
|
32
|
-
* [#174](https://github.com/
|
|
33
|
-
* [#176](https://github.com/
|
|
34
|
-
* [#179](https://github.com/
|
|
35
|
-
* [#178](https://github.com/
|
|
36
|
-
* [#167](https://github.com/
|
|
37
|
-
* [#185](https://github.com/
|
|
51
|
+
* [#91](https://github.com/ruby-grape/grape-swagger/issues/91): Fixed empty field for group parameters' name with type hash or Array - [@dukedave](https://github.com/dukedave).
|
|
52
|
+
* [#154](https://github.com/ruby-grape/grape-swagger/pull/154): Allow classes for type declarations inside documentation - [@mrmargolis](https://github.com/mrmargolis).
|
|
53
|
+
* [#162](https://github.com/ruby-grape/grape-swagger/pull/162): Fix performance issue related to having a large number of models - [@elado](https://github.com/elado).
|
|
54
|
+
* [#169](https://github.com/ruby-grape/grape-swagger/pull/169): Test against multiple versions of Grape - [@dblock](https://github.com/dblock).
|
|
55
|
+
* [#166](https://github.com/ruby-grape/grape-swagger/pull/166): Ensure compatibility with Grape 0.8.0 or newer - [@dblock](https://github.com/dblock).
|
|
56
|
+
* [#174](https://github.com/ruby-grape/grape-swagger/pull/172): Fix problem with using prefix name somewhere in api paths - [@grzesiek](https://github.com/grzesiek).
|
|
57
|
+
* [#176](https://github.com/ruby-grape/grape-swagger/pull/176): Added ability to load nested models recursively - [@sergey-verevkin](https://github.com/sergey-verevkin).
|
|
58
|
+
* [#179](https://github.com/ruby-grape/grape-swagger/pull/179): Document `Virtus::Attribute::Boolean` as boolean - [@eashman](https://github.com/eashman), [@dblock](https://github.com/dblock).
|
|
59
|
+
* [#178](https://github.com/ruby-grape/grape-swagger/issues/178): Fixed `Hash` parameters, now exposed as Swagger `object` types - [@dblock](https://github.com/dblock).
|
|
60
|
+
* [#167](https://github.com/ruby-grape/grape-swagger/pull/167): Support mutli-tenanted APIs, don't cache `base_path` - [@bradrobertson](https://github.com/bradrobertson), (https://github.com/dblock).
|
|
61
|
+
* [#185](https://github.com/ruby-grape/grape-swagger/pull/185): Support strings in `Grape::Entity.expose`'s `:using` option - [@jhollinger](https://github.com/jhollinger).
|
|
38
62
|
|
|
39
63
|
### 0.8.0 (August 30, 2014)
|
|
40
64
|
|
|
41
65
|
#### Features
|
|
42
66
|
|
|
43
|
-
* [#139](https://github.com/
|
|
44
|
-
* [#136](https://github.com/
|
|
45
|
-
* [#100](https://github.com/
|
|
46
|
-
* [#94](https://github.com/
|
|
47
|
-
* [#110](https://github.com/
|
|
48
|
-
* [#114](https://github.com/
|
|
49
|
-
* [#124](https://github.com/
|
|
50
|
-
* [#128](https://github.com/
|
|
51
|
-
* [#132](https://github.com/
|
|
52
|
-
* [#142](https://github.com/
|
|
67
|
+
* [#139](https://github.com/ruby-grape/grape-swagger/pull/139): Added support for `Rack::Multipart::UploadedFile` parameters - [@timgluz](https://github.com/timgluz).
|
|
68
|
+
* [#136](https://github.com/ruby-grape/grape-swagger/pull/136), [#94](https://github.com/ruby-grape/grape-swagger/pull/94): Recurse combination of namespaces when using mounted apps - [@renier](https://github.com/renier).
|
|
69
|
+
* [#100](https://github.com/ruby-grape/grape-swagger/pull/100): Added ability to specify a nickname for an endpoint - [@lhorne](https://github.com/lhorne).
|
|
70
|
+
* [#94](https://github.com/ruby-grape/grape-swagger/pull/94): Added support for namespace descriptions - [@renier](https://github.com/renier).
|
|
71
|
+
* [#110](https://github.com/ruby-grape/grape-swagger/pull/110), [#111](https://github.com/ruby-grape/grape-swagger/pull/111) - Added `responseModel` support - [@bagilevi](https://github.com/bagilevi).
|
|
72
|
+
* [#114](https://github.com/ruby-grape/grape-swagger/pull/114): Added support for generating nested models from composed Grape Entities - [@dspaeth-faber](https://github.com/dspaeth-faber).
|
|
73
|
+
* [#124](https://github.com/ruby-grape/grape-swagger/pull/124): Added ability to change the description and parameters of the API endpoints generated by grape-swagger - [@dblock](https://github.com/dblock).
|
|
74
|
+
* [#128](https://github.com/ruby-grape/grape-swagger/pull/128): Combine global models and endpoint entities - [@dspaeth-faber](https://github.com/dspaeth-faber).
|
|
75
|
+
* [#132](https://github.com/ruby-grape/grape-swagger/pull/132): Addes support for enum values in entity documentation and form parameters - [@Antek-drzewiecki](https://github.com/Antek-drzewiecki).
|
|
76
|
+
* [#142](https://github.com/ruby-grape/grape-swagger/pull/142), [#143](https://github.com/ruby-grape/grape-swagger/pull/143): Added support for kramdown, redcarpet and custom formatters - [@Antek-drzewiecki](https://github.com/Antek-drzewiecki).
|
|
53
77
|
|
|
54
78
|
#### Fixes
|
|
55
79
|
|
|
56
|
-
* [#105](https://github.com/
|
|
57
|
-
* [#87](https://github.com/
|
|
58
|
-
* [#127](https://github.com/
|
|
59
|
-
* [#135](https://github.com/
|
|
80
|
+
* [#105](https://github.com/ruby-grape/grape-swagger/pull/105): Fixed compatibility with Swagger-UI - [@CraigCottingham](https://github.com/CraigCottingham).
|
|
81
|
+
* [#87](https://github.com/ruby-grape/grape-swagger/pull/87): Fixed mapping of `default` to `defaultValue` - [@m-o-e](https://github.com/m-o-e).
|
|
82
|
+
* [#127](https://github.com/ruby-grape/grape-swagger/pull/127): Fixed `undefined method 'reject' for nil:NilClass` error for an invalid route, now returning 404 Not Found - [@dblock](https://github.com/dblock).
|
|
83
|
+
* [#135](https://github.com/ruby-grape/grape-swagger/pull/135): Fixed model inclusion in models with aliased references - [@cdarne](https://github.com/cdarne).
|
|
60
84
|
|
|
61
85
|
#### Dev
|
|
62
86
|
|
|
63
|
-
* [#126](https://github.com/
|
|
87
|
+
* [#126](https://github.com/ruby-grape/grape-swagger/pull/126): Rewritten demo in the `test` folder with CORS enabled - [@dblock](https://github.com/dblock).
|
|
64
88
|
* Rewritten .gemspec and removed Jeweler - [@dblock](https://github.com/dblock).
|
|
65
89
|
* Added `GrapeSwagger::VERSION` - [@dblock](https://github.com/dblock).
|
|
66
90
|
* Added Rubocop, Ruby-style linter - [@dblock](https://github.com/dblock).
|
|
67
91
|
|
|
68
92
|
### 0.7.2 (February 6, 2014)
|
|
69
93
|
|
|
70
|
-
* [#84](https://github.com/
|
|
71
|
-
* [#83](https://github.com/
|
|
72
|
-
* [#79](https://github.com/
|
|
73
|
-
* [#75](https://github.com/
|
|
74
|
-
* [#73](https://github.com/
|
|
75
|
-
* [#69](https://github.com/
|
|
76
|
-
* [#66](https://github.com/
|
|
77
|
-
* [#63](https://github.com/
|
|
78
|
-
* [#62](https://github.com/
|
|
79
|
-
* [#57](https://github.com/
|
|
80
|
-
* [#58](https://github.com/
|
|
81
|
-
* [#56](https://github.com/
|
|
82
|
-
* [#54](https://github.com/
|
|
83
|
-
* [#46](https://github.com/
|
|
94
|
+
* [#84](https://github.com/ruby-grape/grape-swagger/pull/84): Markdown is now Github Flavored Markdown - [@jeromegn](https://github.com/jeromegn).
|
|
95
|
+
* [#83](https://github.com/ruby-grape/grape-swagger/pull/83): Improved support for nested Entity types - [@jeromegn](https://github.com/jeromegn).
|
|
96
|
+
* [#79](https://github.com/ruby-grape/grape-swagger/pull/79): Added `dataType` to the `params` output - [@Phobos98](https://github.com/Phobos98).
|
|
97
|
+
* [#75](https://github.com/ruby-grape/grape-swagger/pull/75), [#82](https://github.com/ruby-grape/grape-swagger/pull/82): Added Swagger 1.2 support - [@joelvh](https://github.com/joelvh), [@jeromegn](https://github.com/jeromegn).
|
|
98
|
+
* [#73](https://github.com/ruby-grape/grape-swagger/pull/73): Added the ability to add additional API `info` - [@mattbeedle](https://github.com/mattbeedle).
|
|
99
|
+
* [#69](https://github.com/ruby-grape/grape-swagger/pull/69): Make relative `base_path` values absolute - [@dm1try](https://github.com/dm1try).
|
|
100
|
+
* [#66](https://github.com/ruby-grape/grape-swagger/pull/66): Fixed documentation generated for paths that don't match the base URL pattern - [@swistaczek](https://github.com/swistaczek).
|
|
101
|
+
* [#63](https://github.com/ruby-grape/grape-swagger/pull/63): Added support for hiding endpoints from the documentation - [@arturoherrero](https://github.com/arturoherrero).
|
|
102
|
+
* [#62](https://github.com/ruby-grape/grape-swagger/pull/62): Fixed handling of URLs with the `-` character - [@dadario](https://github.com/dadario).
|
|
103
|
+
* [#57](https://github.com/ruby-grape/grape-swagger/pull/57): Fixed documenting of multiple API versions - [@Drakula2k](https://github.com/Drakula2k).
|
|
104
|
+
* [#58](https://github.com/ruby-grape/grape-swagger/pull/58): Fixed resource groupings for prefixed APIs - [@aew](https://github.com/aew).
|
|
105
|
+
* [#56](https://github.com/ruby-grape/grape-swagger/pull/56): Fixed `hide_documentation_path` on prefixed APIs - [@spier](https://github.com/spier).
|
|
106
|
+
* [#54](https://github.com/ruby-grape/grape-swagger/pull/54): Adding support for generating swagger `responseClass` and models from Grape Entities - [@calebwoods](https://github.com/calebwoods).
|
|
107
|
+
* [#46](https://github.com/ruby-grape/grape-swagger/pull/46): Fixed translating parameter `type` to String, enables using Mongoid fields as parameter definitions - [@dblock](https://github.com/dblock).
|
|
84
108
|
|
|
85
109
|
### 0.6.0 (June 19, 2013)
|
|
86
110
|
|
|
87
111
|
* Added Rails 4 support - [@jrhe](https://github.com/jrhe).
|
|
88
112
|
* Fix: document APIs at root level - [@dblock](https://github.com/dblock).
|
|
89
|
-
* Added support for procs in basepath - [@
|
|
113
|
+
* Added support for procs in basepath - [@ruby-grape](https://github.com/ruby-grape).
|
|
90
114
|
* Support both `:desc` and `:description` when describing parameters - [@dblock](https://github.com/dblock).
|
|
91
115
|
* Fix: allow parameters such as `name[]` - [@dblock](https://github.com/dblock).
|
|
92
116
|
|
|
93
117
|
### 0.5.0 (March 28, 2013)
|
|
94
118
|
|
|
95
|
-
* Added Grape 0.5.0 support - [@
|
|
119
|
+
* Added Grape 0.5.0 support - [@ruby-grape](https://github.com/ruby-grape).
|
|
96
120
|
|
|
97
121
|
### 0.4.0 (March 28, 2013)
|
|
98
122
|
|
|
@@ -101,28 +125,28 @@
|
|
|
101
125
|
### 0.3.0 (October 19, 2012)
|
|
102
126
|
|
|
103
127
|
* Added version support - [@agileanimal](https://github.com/agileanimal), [@fknappe](https://github.com/fknappe).
|
|
104
|
-
* Added support for nested parameters - [@
|
|
128
|
+
* Added support for nested parameters - [@ruby-grape](https://github.com/ruby-grape).
|
|
105
129
|
* Added basic support for specifying parameters that need to be passed in the header - [@agileanimal](https://github.com/agileanimal).
|
|
106
|
-
* Add possibility to hide the documentation paths in the generated swagger documentation - [@
|
|
130
|
+
* Add possibility to hide the documentation paths in the generated swagger documentation - [@ruby-grape](https://github.com/ruby-grape).
|
|
107
131
|
|
|
108
132
|
### 0.2.1 (August 17, 2012)
|
|
109
133
|
|
|
110
|
-
* Added support for markdown in notes field - [@
|
|
134
|
+
* Added support for markdown in notes field - [@ruby-grape](https://github.com/ruby-grape).
|
|
111
135
|
* Fix: compatibility with Rails - [@qwert666](https://github.com/qwert666).
|
|
112
|
-
* Fix: swagger UI history - [@
|
|
136
|
+
* Fix: swagger UI history - [@ruby-grape](https://github.com/ruby-grape).
|
|
113
137
|
|
|
114
138
|
### 0.2.0 (July 27, 2012)
|
|
115
139
|
|
|
116
|
-
* Use resource as root for swagger - [@
|
|
117
|
-
* Added support for file uploads, and proper `paramType` - [@
|
|
140
|
+
* Use resource as root for swagger - [@ruby-grape](https://github.com/ruby-grape).
|
|
141
|
+
* Added support for file uploads, and proper `paramType` - [@ruby-grape](https://github.com/ruby-grape).
|
|
118
142
|
* Added tests - [@nathanvda](https://github.com/nathanvda).
|
|
119
143
|
|
|
120
144
|
### 0.1.0 (July 19, 2012)
|
|
121
145
|
|
|
122
|
-
* Added some configurability to the generated documentation - [@
|
|
123
|
-
* Adapted to rails plugin structure - [@
|
|
124
|
-
* Allowed cross origin, so swagger can be used from official site - [@
|
|
146
|
+
* Added some configurability to the generated documentation - [@ruby-grape](https://github.com/ruby-grape).
|
|
147
|
+
* Adapted to rails plugin structure - [@ruby-grape](https://github.com/ruby-grape).
|
|
148
|
+
* Allowed cross origin, so swagger can be used from official site - [@ruby-grape](https://github.com/ruby-grape).
|
|
125
149
|
|
|
126
150
|
### 0.0.0 (July 19, 2012)
|
|
127
151
|
|
|
128
|
-
* Initial public release - [@
|
|
152
|
+
* Initial public release - [@ruby-grape](https://github.com/ruby-grape).
|
data/CONTRIBUTING.md
CHANGED
|
@@ -1,20 +1,20 @@
|
|
|
1
1
|
# Contributing to Grape-Swagger
|
|
2
2
|
|
|
3
|
-
This project is work of [many contributors](https://github.com/
|
|
4
|
-
You're encouraged to submit [pull requests](https://github.com/
|
|
5
|
-
[propose features and discuss issues](https://github.com/
|
|
3
|
+
This project is work of [many contributors](https://github.com/ruby-grape/grape-swagger/graphs/contributors).
|
|
4
|
+
You're encouraged to submit [pull requests](https://github.com/ruby-grape/grape-swagger/pulls),
|
|
5
|
+
[propose features and discuss issues](https://github.com/ruby-grape/grape-swagger/issues).
|
|
6
6
|
When in doubt, ask a question in the [Grape Google Group](http://groups.google.com/group/ruby-grape).
|
|
7
7
|
|
|
8
8
|
In the examples below, substitute your Github username for `contributor` in URLs.
|
|
9
9
|
|
|
10
10
|
## Fork the Project
|
|
11
11
|
|
|
12
|
-
Fork the [project on Github](https://github.com/
|
|
12
|
+
Fork the [project on Github](https://github.com/ruby-grape/grape-swagger) and check out your copy.
|
|
13
13
|
|
|
14
14
|
```
|
|
15
15
|
git clone https://github.com/contributor/grape-swagger.git
|
|
16
16
|
cd grape-swagger
|
|
17
|
-
git remote add upstream https://github.com/
|
|
17
|
+
git remote add upstream https://github.com/ruby-grape/grape-swagger.git
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
## Create a Topic Branch
|
|
@@ -47,7 +47,7 @@ We definitely appreciate pull requests that highlight or reproduce a problem, ev
|
|
|
47
47
|
|
|
48
48
|
Implement your feature or bug fix.
|
|
49
49
|
|
|
50
|
-
Ruby style is enforced with [
|
|
50
|
+
Ruby style is enforced with [RuboCop](https://github.com/bbatsov/rubocop).
|
|
51
51
|
Run `bundle exec rubocop` and fix any style issues highlighted.
|
|
52
52
|
|
|
53
53
|
Make sure that `bundle exec rake` completes without errors.
|
|
@@ -85,7 +85,7 @@ git push origin my-feature-branch
|
|
|
85
85
|
|
|
86
86
|
## Make a Pull Request
|
|
87
87
|
|
|
88
|
-
Go to https://github.com/contributor/grape and select your feature branch.
|
|
88
|
+
Go to https://github.com/contributor/grape-swagger and select your feature branch.
|
|
89
89
|
Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.
|
|
90
90
|
|
|
91
91
|
## Rebase
|
|
@@ -103,7 +103,7 @@ git push origin my-feature-branch -f
|
|
|
103
103
|
Update the [CHANGELOG](CHANGELOG.md) with the pull request number. A typical entry looks as follows.
|
|
104
104
|
|
|
105
105
|
```
|
|
106
|
-
* [#123](https://github.com/
|
|
106
|
+
* [#123](https://github.com/ruby-grape/grape-swagger/pull/123): Reticulated splines - [@contributor](https://github.com/contributor).
|
|
107
107
|
```
|
|
108
108
|
|
|
109
109
|
Amend your previous commit and force push the changes.
|
data/Gemfile
CHANGED
data/README.md
CHANGED
|
@@ -1,20 +1,24 @@
|
|
|
1
1
|
# grape-swagger
|
|
2
2
|
|
|
3
|
-
[](http://badge.fury.io/rb/grape-swagger)
|
|
4
|
+
[](https://travis-ci.org/ruby-grape/grape-swagger)
|
|
5
|
+
[](https://codeclimate.com/github/ruby-grape/grape-swagger)
|
|
6
6
|
|
|
7
7
|
## What is grape-swagger?
|
|
8
8
|
|
|
9
|
-
The grape-swagger gem provides an autogenerated documentation for your [Grape](https://github.com/
|
|
9
|
+
The grape-swagger gem provides an autogenerated documentation for your [Grape](https://github.com/ruby-grape/grape) API. The generated documentation is Swagger-compliant, meaning it can easily be discovered in [Swagger UI](https://github.com/wordnik/swagger-ui). You should be able to point [the petstore demo](http://petstore.swagger.io/) to your API.
|
|
10
10
|
|
|
11
11
|
|
|
12
12
|
|
|
13
13
|
## Related Projects
|
|
14
14
|
|
|
15
|
-
* [Grape](https://github.com/
|
|
15
|
+
* [Grape](https://github.com/ruby-grape/grape)
|
|
16
16
|
* [Swagger UI](https://github.com/wordnik/swagger-ui)
|
|
17
17
|
|
|
18
|
+
## Swagger-Spec
|
|
19
|
+
|
|
20
|
+
Grape-swagger generates documentation per [Swagger Spec 1.2](https://github.com/swagger-api/swagger-spec/blob/master/versions/1.2.md).
|
|
21
|
+
|
|
18
22
|
## Installation
|
|
19
23
|
|
|
20
24
|
Add to your Gemfile:
|
|
@@ -27,7 +31,7 @@ Please see [UPGRADING](UPGRADING.md) when upgrading from a previous version.
|
|
|
27
31
|
|
|
28
32
|
## Usage
|
|
29
33
|
|
|
30
|
-
Mount all your different APIs (with ```Grape::API``` superclass) on a root node. In the root class definition, include ```add_swagger_documentation```, this sets up the system and registers the documentation on '/swagger_doc
|
|
34
|
+
Mount all your different APIs (with ```Grape::API``` superclass) on a root node. In the root class definition, include ```add_swagger_documentation```, this sets up the system and registers the documentation on '/swagger_doc'. See [example/api.rb](example/api.rb) for a simple demo.
|
|
31
35
|
|
|
32
36
|
|
|
33
37
|
``` ruby
|
|
@@ -43,7 +47,7 @@ module API
|
|
|
43
47
|
end
|
|
44
48
|
```
|
|
45
49
|
|
|
46
|
-
To explore your API, either download [Swagger UI](https://github.com/wordnik/swagger-ui) and set it up yourself or go to the [online swagger demo](http://petstore.swagger.wordnik.com/) and enter your localhost url documentation root in the url field (probably something in the line of http://localhost:3000/swagger_doc
|
|
50
|
+
To explore your API, either download [Swagger UI](https://github.com/wordnik/swagger-ui) and set it up yourself or go to the [online swagger demo](http://petstore.swagger.wordnik.com/) and enter your localhost url documentation root in the url field (probably something in the line of http://localhost:3000/swagger_doc).
|
|
47
51
|
|
|
48
52
|
### CORS
|
|
49
53
|
|
|
@@ -86,7 +90,7 @@ API class name.
|
|
|
86
90
|
|
|
87
91
|
#### markdown
|
|
88
92
|
|
|
89
|
-
Allow markdown in `notes`, default is `nil`. (disabled) See below for details.
|
|
93
|
+
Allow markdown in `detail`/`notes`, default is `nil`. (disabled) See below for details.
|
|
90
94
|
|
|
91
95
|
#### hide_format
|
|
92
96
|
|
|
@@ -110,7 +114,7 @@ Add `basePath` key to the JSON documentation, default is `true`.
|
|
|
110
114
|
|
|
111
115
|
#### models
|
|
112
116
|
|
|
113
|
-
A list of entities to document. Combine with the [grape-entity](https://github.com/
|
|
117
|
+
A list of entities to document. Combine with the [grape-entity](https://github.com/ruby-grape/grape-entity) gem. See below for details.
|
|
114
118
|
|
|
115
119
|
#### hide_documentation_path
|
|
116
120
|
|
|
@@ -191,6 +195,54 @@ You can specify a swagger nickname to use instead of the auto generated name by
|
|
|
191
195
|
desc 'Get a full list of pets', nickname: 'getAllPets'
|
|
192
196
|
```
|
|
193
197
|
|
|
198
|
+
## Defining an endpoint as array
|
|
199
|
+
|
|
200
|
+
You can define an endpoint as array by adding `is_array` in the description:
|
|
201
|
+
|
|
202
|
+
``` ruby
|
|
203
|
+
desc 'Get a full list of pets', is_array: true
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
## Using an options hash
|
|
207
|
+
|
|
208
|
+
The Grape DSL supports either an options hash or a restricted block to pass settings. Passing the `nickname`, `hidden` and `is_array` options together with response codes is only possible when passing an options hash.
|
|
209
|
+
Since the syntax differs you'll need to adjust it accordingly:
|
|
210
|
+
|
|
211
|
+
``` ruby
|
|
212
|
+
desc 'Get all kittens!', {
|
|
213
|
+
:hidden => true,
|
|
214
|
+
:is_array => true,
|
|
215
|
+
:nickname => 'getKittens',
|
|
216
|
+
:entity => Entities::Kitten, # use entity instead of success
|
|
217
|
+
:http_codes => [[401, 'KittenBitesError', Entities::BadKitten]] # use http_codes instead of failure
|
|
218
|
+
}
|
|
219
|
+
get '/kittens' do
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## Specify endpoint details
|
|
223
|
+
|
|
224
|
+
To specify further details for an endpoint, use the `detail` option within a block passed to `desc`:
|
|
225
|
+
|
|
226
|
+
``` ruby
|
|
227
|
+
desc 'Get all kittens!' do
|
|
228
|
+
detail 'this will expose all the kittens'
|
|
229
|
+
end
|
|
230
|
+
get '/kittens' do
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
## Overriding param type
|
|
234
|
+
|
|
235
|
+
You can override paramType in POST|PUT methods to query, using the documentation hash.
|
|
236
|
+
|
|
237
|
+
``` ruby
|
|
238
|
+
params do
|
|
239
|
+
requires :action, type: Symbol, values: [:PAUSE, :RESUME, :STOP], documentation: { param_type: 'query' }
|
|
240
|
+
end
|
|
241
|
+
post :act do
|
|
242
|
+
...
|
|
243
|
+
end
|
|
244
|
+
```
|
|
245
|
+
|
|
194
246
|
## Expose nested namespace as standalone route
|
|
195
247
|
Use the `nested: false` property in the `swagger` option to make nested namespaces appear as standalone resources.
|
|
196
248
|
This option can help to structure and keep the swagger schema simple.
|
|
@@ -200,9 +252,9 @@ This option can help to structure and keep the swagger schema simple.
|
|
|
200
252
|
...
|
|
201
253
|
end
|
|
202
254
|
end
|
|
203
|
-
|
|
255
|
+
|
|
204
256
|
All routes that belong to this namespace (here: the `GET /order_id`) will then be assigned to the `store_order` route instead of the `store` resource route.
|
|
205
|
-
|
|
257
|
+
|
|
206
258
|
It is also possible to expose a namspace within another already exposed namespace:
|
|
207
259
|
|
|
208
260
|
namespace 'store/order', desc: 'Order operations within a store', swagger: { nested: false } do
|
|
@@ -229,6 +281,28 @@ The name should not contain whitespaces or any other special characters due to f
|
|
|
229
281
|
end
|
|
230
282
|
end
|
|
231
283
|
|
|
284
|
+
## Additional documentation
|
|
285
|
+
|
|
286
|
+
## Setting a Swagger defaultValue
|
|
287
|
+
|
|
288
|
+
Grape allows for an additional documentation hash to be passed to a parameter.
|
|
289
|
+
|
|
290
|
+
params do
|
|
291
|
+
requires :id, type: Integer, desc: 'Coffee ID'
|
|
292
|
+
requires :temperature, type: Integer, desc: 'Temperature of the coffee in celcius', documentation: { example: 72 }
|
|
293
|
+
end
|
|
294
|
+
|
|
295
|
+
The example parameter will populate the Swagger UI with the example value, and can be used for optional or required parameters.
|
|
296
|
+
|
|
297
|
+
Grape uses the option `default` to set a default value for optional parameters. This is different in that Grape will set your parameter to the provided default if the parameter is omitted, whereas the example value above will only set the value in the UI itself. This will set the Swagger `defaultValue` to the provided value. Note that the example value will override the Grape default value.
|
|
298
|
+
|
|
299
|
+
|
|
300
|
+
params do
|
|
301
|
+
requires :id, type: Integer, desc: 'Coffee ID'
|
|
302
|
+
optional :temperature, type: Integer, desc: 'Temperature of the coffee in celcius', default: 72
|
|
303
|
+
end
|
|
304
|
+
|
|
305
|
+
|
|
232
306
|
## Grape Entities
|
|
233
307
|
|
|
234
308
|
Add the [grape-entity](https://github.com/agileanimal/grape-entity) gem to our Gemfile.
|
|
@@ -336,9 +410,9 @@ module API
|
|
|
336
410
|
end
|
|
337
411
|
```
|
|
338
412
|
|
|
339
|
-
## Markdown in Notes
|
|
413
|
+
## Markdown in Detail/Notes
|
|
340
414
|
|
|
341
|
-
The grape-swagger gem allows you to add an explanation in markdown in the notes field. Which would result in proper formatted markdown in Swagger UI.
|
|
415
|
+
The grape-swagger gem allows you to add an explanation in markdown in the detail/notes field. Which would result in proper formatted markdown in Swagger UI.
|
|
342
416
|
Grape-swagger uses adapters for several markdown formatters. It includes adapters for [kramdown](http://kramdown.rubyforge.org) (kramdown [syntax](http://kramdown.rubyforge.org/syntax.html)) and [redcarpet](https://github.com/vmg/redcarpet).
|
|
343
417
|
The adapters are packed in the GrapeSwagger::Markdown modules. We do not include the markdown gems in our gemfile, so be sure to include or install the depended gems.
|
|
344
418
|
|
|
@@ -362,8 +436,8 @@ add_swagger_documentation(
|
|
|
362
436
|
Finally you can write endpoint descriptions the with markdown enabled.
|
|
363
437
|
|
|
364
438
|
``` ruby
|
|
365
|
-
desc "Reserve a burger in heaven"
|
|
366
|
-
|
|
439
|
+
desc "Reserve a burger in heaven" do
|
|
440
|
+
detail <<-NOTE
|
|
367
441
|
Veggie Burgers in Heaven
|
|
368
442
|
-----------------
|
|
369
443
|
|
|
@@ -379,7 +453,7 @@ desc "Reserve a burger in heaven", {
|
|
|
379
453
|
* _Will go to Heaven:_ Probably
|
|
380
454
|
* _Will go to Hell:_ Probably not
|
|
381
455
|
NOTE
|
|
382
|
-
|
|
456
|
+
end
|
|
383
457
|
```
|
|
384
458
|
|
|
385
459
|
### Redcarpet
|