dry_crud_jsonapi_swagger 0.1.1 → 0.2.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +14 -4
- data/app/controllers/dry_crud_jsonapi_swagger/apidocs_controller.rb +2 -2
- data/app/domain/dry_crud_jsonapi_swagger/helper.rb +45 -28
- data/app/domain/dry_crud_jsonapi_swagger/tags_setup.rb +28 -17
- data/lib/dry_crud_jsonapi_swagger.rb +13 -1
- data/lib/dry_crud_jsonapi_swagger/param.rb +3 -0
- data/lib/dry_crud_jsonapi_swagger/version.rb +1 -1
- metadata +3 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: c9d805f02243eba631d4656adc5a7d7570367c11cdf7833f998d9beaf37336e6
|
4
|
+
data.tar.gz: 76ff302864cd450f719890d3742c547ac995177f7174ce0f04727176d4cae6a6
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 9f6a9025c590e41addc7fe4fba525c97632ea10f6acb60d336a6d592d47bb5ff2ad4103a53d871eabb8f31dc8ebf5712f8433c94653fa6ca66a7cda7a1c877ab
|
7
|
+
data.tar.gz: b7e56393467e77e5979b0d3d958bb739c9befb8de9a1c5197a8795c245eac5f53973fed6b925ffa205f44c5c0c83ca37eb91d94c265732be8716221be75fca60
|
data/README.md
CHANGED
@@ -1,8 +1,6 @@
|
|
1
1
|
# DryCrudJsonapiSwagger
|
2
|
-
|
3
|
-
|
4
|
-
## Usage
|
5
|
-
How to use my plugin.
|
2
|
+
This Gem provides a Rails Engine to generate the api documentation for Applications based on [`dry_crud_jsonapi`].
|
3
|
+
The documentation is exposed as a swagger v2 specification and can be viewed with the included, interactive swagger web interface.
|
6
4
|
|
7
5
|
## Installation
|
8
6
|
Add this line to your application's Gemfile:
|
@@ -21,8 +19,20 @@ Or install it yourself as:
|
|
21
19
|
$ gem install dry_crud_jsonapi_swagger
|
22
20
|
```
|
23
21
|
|
22
|
+
## Usage
|
23
|
+
* Implement the `json:api` in your application with [`dry_crud_jsonapi`]
|
24
|
+
* Mount the engine in your `routes.rb`:
|
25
|
+
|
26
|
+
mount DryCrudJsonapiSwagger::Engine => '/apidocs'
|
27
|
+
|
28
|
+
The swagger webinterface is available on the mount path, i.e. `/apidocs`.
|
29
|
+
To get the swagger v2 specification, just add `/swagger.json` to the mount path, i.e. `/apidocs/swagger.json`.
|
30
|
+
|
24
31
|
## Contributing
|
25
32
|
Contribution directions go here.
|
26
33
|
|
27
34
|
## License
|
28
35
|
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
|
36
|
+
|
37
|
+
|
38
|
+
[`dry_crud_jsonapi`]: https://github.com/puzzle/dry_crud_jsonapi
|
@@ -24,8 +24,8 @@ module DryCrudJsonapiSwagger
|
|
24
24
|
end
|
25
25
|
|
26
26
|
def json_api_controllers
|
27
|
-
|
28
|
-
controller.
|
27
|
+
ActionController::Base.descendants.select do |controller|
|
28
|
+
controller.include?(DryCrudJsonapi) && controller&.model_class.present?
|
29
29
|
end
|
30
30
|
end
|
31
31
|
end
|
@@ -37,21 +37,20 @@ module DryCrudJsonapiSwagger
|
|
37
37
|
nested_class.model_class.model_name
|
38
38
|
end
|
39
39
|
|
40
|
-
def
|
41
|
-
|
42
|
-
|
43
|
-
|
44
|
-
#
|
45
|
-
# relationships += controller.model_class
|
46
|
-
# .reflect_on_all_associations(:has_many)
|
47
|
-
# .map(&:name).sort
|
40
|
+
def include_description(controller = controller_class)
|
41
|
+
<<~DESC
|
42
|
+
Available primary relations:
|
43
|
+
#{includes(controller.model_class).map { |inc| "* #{inc}" }.join("\n")}
|
48
44
|
|
49
|
-
|
50
|
-
.reflect_on_all_associations
|
51
|
-
.map(&:name).sort
|
45
|
+
Separate values with a comma
|
52
46
|
|
53
|
-
|
54
|
-
|
47
|
+
To include sub-relations, specify the relationship chain with the elements separated by '.'
|
48
|
+
i.e. "employee.address.town"
|
49
|
+
DESC
|
50
|
+
end
|
51
|
+
|
52
|
+
def includes(model_class)
|
53
|
+
model_class.reflect_on_all_associations.reject(&:polymorphic?).map(&:name).sort
|
55
54
|
end
|
56
55
|
|
57
56
|
def path_spec(swagger_doc, helper, type) # rubocop:disable Metrics/MethodLength
|
@@ -64,7 +63,7 @@ module DryCrudJsonapiSwagger
|
|
64
63
|
|
65
64
|
swagger_doc.operation :get do
|
66
65
|
key :summary, summary
|
67
|
-
helper.
|
66
|
+
helper.setup_tag(self)
|
68
67
|
helper.parameters(self, helper, type)
|
69
68
|
response 200 do
|
70
69
|
key :description, summary + ' Response'
|
@@ -73,16 +72,17 @@ module DryCrudJsonapiSwagger
|
|
73
72
|
end
|
74
73
|
end
|
75
74
|
|
76
|
-
def
|
77
|
-
|
78
|
-
|
79
|
-
TagsSetup.path_tag(@path)
|
80
|
-
]
|
75
|
+
def setup_tag(swagger_doc)
|
76
|
+
tag = TagsSetup.new.path_tag(@path)
|
77
|
+
swagger_doc.key :tags, [tag] if tag.present?
|
81
78
|
end
|
82
79
|
|
83
80
|
def parameters(swagger_doc, helper, type)
|
84
81
|
case type.to_sym
|
85
|
-
when :
|
82
|
+
when :index
|
83
|
+
parameter_custom swagger_doc, type
|
84
|
+
when :show, :nested
|
85
|
+
parameter_id swagger_doc, helper
|
86
86
|
end
|
87
87
|
|
88
88
|
parameter_include swagger_doc, helper, type
|
@@ -100,15 +100,32 @@ module DryCrudJsonapiSwagger
|
|
100
100
|
|
101
101
|
def parameter_include(swagger_doc, helper, type) # rubocop:disable Metrics/MethodLength
|
102
102
|
desc = case type.to_sym
|
103
|
-
|
104
|
-
|
103
|
+
when :index, :show then include_description
|
104
|
+
when :nested then include_description(helper.nested_class)
|
105
105
|
end
|
106
106
|
swagger_doc.parameter do
|
107
|
-
key :name,
|
108
|
-
key :in,
|
109
|
-
key :description,
|
110
|
-
key :required,
|
111
|
-
key :type,
|
107
|
+
key :name, :include
|
108
|
+
key :in, :query
|
109
|
+
key :description, desc
|
110
|
+
key :required, false
|
111
|
+
key :type, :array
|
112
|
+
key :collectionFormat, :csv
|
113
|
+
items do
|
114
|
+
key :type, :string
|
115
|
+
end
|
116
|
+
end
|
117
|
+
end
|
118
|
+
|
119
|
+
def parameter_custom(swagger_doc, type)
|
120
|
+
controller_class.swagger_params[type].each do |param|
|
121
|
+
swagger_doc.parameter do
|
122
|
+
key :name, param.name
|
123
|
+
key :in, :query
|
124
|
+
key :description, param.description
|
125
|
+
key :required, param.required
|
126
|
+
key :type, param.type
|
127
|
+
key :enum, param.enum if param.enum.present?
|
128
|
+
end
|
112
129
|
end
|
113
130
|
end
|
114
131
|
|
@@ -126,4 +143,4 @@ module DryCrudJsonapiSwagger
|
|
126
143
|
end
|
127
144
|
end
|
128
145
|
end
|
129
|
-
end
|
146
|
+
end
|
@@ -1,3 +1,5 @@
|
|
1
|
+
require 'yaml'
|
2
|
+
|
1
3
|
module DryCrudJsonapiSwagger
|
2
4
|
class TagsSetup
|
3
5
|
|
@@ -9,37 +11,46 @@ module DryCrudJsonapiSwagger
|
|
9
11
|
setup_tags
|
10
12
|
end
|
11
13
|
|
12
|
-
def
|
13
|
-
|
14
|
+
def path_tag(path)
|
15
|
+
customized_tag(path) || derived_tag(path)
|
14
16
|
end
|
15
17
|
|
16
|
-
|
17
|
-
tags.each do |tag|
|
18
|
-
next if tag['include'].blank?
|
18
|
+
private
|
19
19
|
|
20
|
-
|
21
|
-
|
22
|
-
|
20
|
+
def customized_tag(path)
|
21
|
+
customized_tags.each do |tag|
|
22
|
+
next if tag['include'].blank?
|
23
23
|
|
24
|
+
return tag['name'] if tag['include'].any? { |inc| path =~ /#{inc}/i }
|
24
25
|
end
|
26
|
+
|
27
|
+
nil
|
25
28
|
end
|
26
29
|
|
27
|
-
|
28
|
-
|
30
|
+
def derived_tag(path)
|
31
|
+
path.gsub(%r(/{[^}]+}), '').gsub('/', ' ').strip.titleize
|
32
|
+
end
|
29
33
|
|
30
34
|
def setup_tags
|
31
|
-
|
35
|
+
customized_tags.each do |tag|
|
32
36
|
@swagger_doc.tags tag.slice('name', 'description', 'externalDocs')
|
33
37
|
end
|
34
38
|
end
|
35
39
|
|
36
|
-
def
|
37
|
-
@
|
40
|
+
def customized_tags
|
41
|
+
@customized_tags ||= load_customized_tags
|
38
42
|
end
|
39
43
|
|
40
|
-
def
|
41
|
-
|
42
|
-
|
44
|
+
def load_customized_tags
|
45
|
+
return [] unless File.exist?(Rails.root.join('config', 'swagger-tags.yml'))
|
46
|
+
|
47
|
+
YAML.load_file(Rails.root.join('config', 'swagger-tags.yml')).yield_self do |tags_data|
|
48
|
+
raise('Your config/swagger-tags.yml contains malformed data') unless
|
49
|
+
Array.wrap(tags_data&.keys).include?('tags') &&
|
50
|
+
Array.wrap(tags_data['tags']).all? { |tag| tag.is_a?(Hash) }
|
51
|
+
|
52
|
+
Array.wrap(tags_data['tags'])
|
53
|
+
end
|
43
54
|
end
|
44
55
|
end
|
45
|
-
end
|
56
|
+
end
|
@@ -1,5 +1,17 @@
|
|
1
1
|
require "dry_crud_jsonapi_swagger/engine"
|
2
|
+
require "dry_crud_jsonapi_swagger/param"
|
2
3
|
|
3
4
|
module DryCrudJsonapiSwagger
|
4
|
-
|
5
|
+
extend ActiveSupport::Concern
|
6
|
+
|
7
|
+
included do
|
8
|
+
class_attribute :swagger_params, instance_writer: false
|
9
|
+
self.swagger_params = Hash.new { |hash, key| hash[key] = [] }
|
10
|
+
end
|
11
|
+
|
12
|
+
class_methods do
|
13
|
+
def swagger_param(action, name, type: type, description: nil, required: false, enum: nil)
|
14
|
+
swagger_params[action.to_sym] << Param.new(name, type, description, required, enum)
|
15
|
+
end
|
16
|
+
end
|
5
17
|
end
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: dry_crud_jsonapi_swagger
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.2.0
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Daniel Illi
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2019-
|
11
|
+
date: 2019-02-07 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: bundler
|
@@ -99,6 +99,7 @@ files:
|
|
99
99
|
- config/routes.rb
|
100
100
|
- lib/dry_crud_jsonapi_swagger.rb
|
101
101
|
- lib/dry_crud_jsonapi_swagger/engine.rb
|
102
|
+
- lib/dry_crud_jsonapi_swagger/param.rb
|
102
103
|
- lib/dry_crud_jsonapi_swagger/version.rb
|
103
104
|
homepage: https://rubygems.org/gems/dry_crud_jsonapi_swagger
|
104
105
|
licenses:
|