swaggard 4.1.1 → 4.3.0
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 +4 -4
- data/README.md +8 -0
- data/lib/swaggard/configuration.rb +8 -1
- data/lib/swaggard/swagger/operation.rb +8 -2
- data/lib/swaggard/swagger/tag.rb +1 -1
- data/lib/swaggard/version.rb +1 -1
- data/lib/swaggard.rb +12 -0
- data/spec/fixtures/api.json +2 -1
- data/spec/fixtures/dummy/app/controllers/pets_controller.rb +1 -0
- data/spec/swaggard/swagger/operation_spec.rb +92 -0
- metadata +3 -3
- data/spec/fixtures/dummy/log/development.log +0 -0
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: e58966e12de0580a4352f142f3dc5f76c75bef3366a81861acb1f7d5e1e7cf5b
|
|
4
|
+
data.tar.gz: af8536b1d6047dd86f57500cba80b15c14a3ef127c394cf188d61c627ecb8af8
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 03db5dfd301998070525bb9eaf49910c99c2f7304ccbbbdbfa565a1556623a789131e6973c907f33e21a20f6d08bcc64205bb50fb0b80baea29ba27fd8af8afe
|
|
7
|
+
data.tar.gz: 9c2d9d53a91b12f792fa0240ac31fdb90f1b7560d08d5416d2ed52931dcb546168236375b02b7a413599f8ac186f42991cff0ca78fee7446d8f2ebf3d822572b
|
data/README.md
CHANGED
|
@@ -159,6 +159,14 @@ To document all controllers including those without a `@tag`:
|
|
|
159
159
|
config.ignore_untagged_controllers = false
|
|
160
160
|
end
|
|
161
161
|
|
|
162
|
+
To keep RBS inline type annotations (Sorbet or Steep `#:` signatures and their `#|` continuation lines) out of the docs, so an action whose only comment is a signature stays undocumented:
|
|
163
|
+
|
|
164
|
+
Swaggard.configure do |config|
|
|
165
|
+
config.ignore_rbs_comments = true
|
|
166
|
+
end
|
|
167
|
+
|
|
168
|
+
This drops every docstring line that starts with `:` or `|`, so a description line written as `# : text` is dropped too.
|
|
169
|
+
|
|
162
170
|
|
|
163
171
|
### Models
|
|
164
172
|
|
|
@@ -21,7 +21,8 @@ module Swaggard
|
|
|
21
21
|
:language, :additional_parameters, :schemes, :ignore_undocumented_paths,
|
|
22
22
|
:license_name, :exclude_base_path_from_paths, :default_response_description,
|
|
23
23
|
:default_response_status_code, :excluded_paths, :path_parameter_description,
|
|
24
|
-
:ignore_put_if_patch_exists, :ignore_untagged_controllers
|
|
24
|
+
:ignore_put_if_patch_exists, :ignore_untagged_controllers,
|
|
25
|
+
:ignore_rbs_comments
|
|
25
26
|
|
|
26
27
|
def api_version
|
|
27
28
|
@api_version ||= '0.1'
|
|
@@ -119,6 +120,12 @@ module Swaggard
|
|
|
119
120
|
@ignore_untagged_controllers = true
|
|
120
121
|
end
|
|
121
122
|
|
|
123
|
+
def ignore_rbs_comments
|
|
124
|
+
return @ignore_rbs_comments unless @ignore_rbs_comments.nil?
|
|
125
|
+
|
|
126
|
+
@ignore_rbs_comments = false
|
|
127
|
+
end
|
|
128
|
+
|
|
122
129
|
def exclude_base_path_from_paths
|
|
123
130
|
return @exclude_base_path_from_paths unless @exclude_base_path_from_paths.nil?
|
|
124
131
|
|
|
@@ -16,11 +16,13 @@ module Swaggard
|
|
|
16
16
|
def initialize(yard_object, tag, path, verb, path_params)
|
|
17
17
|
@name = yard_object.name.to_s
|
|
18
18
|
@tag = tag
|
|
19
|
-
|
|
19
|
+
docstring = Swaggard.docstring(yard_object)
|
|
20
|
+
@summary = (docstring.lines.first || '').chomp
|
|
20
21
|
@parameters = []
|
|
21
22
|
@responses = []
|
|
23
|
+
@deprecated = false
|
|
22
24
|
|
|
23
|
-
@description = (
|
|
25
|
+
@description = (docstring.lines[1..-1] || []).map(&:chomp).reject(&:empty?).compact.join("\n")
|
|
24
26
|
@http_method = verb
|
|
25
27
|
@path = path
|
|
26
28
|
|
|
@@ -32,6 +34,8 @@ module Swaggard
|
|
|
32
34
|
case yard_tag.tag_name
|
|
33
35
|
when 'operation_id'
|
|
34
36
|
@operation_id = "#{@tag.name}.#{value}"
|
|
37
|
+
when 'deprecated'
|
|
38
|
+
@deprecated = true
|
|
35
39
|
when 'query_parameter'
|
|
36
40
|
@parameters << Parameters::Query.new(value)
|
|
37
41
|
when 'form_parameter'
|
|
@@ -98,6 +102,8 @@ module Swaggard
|
|
|
98
102
|
doc['requestBody'] = build_form_request_body(form_params)
|
|
99
103
|
end
|
|
100
104
|
|
|
105
|
+
doc['deprecated'] = true if @deprecated
|
|
106
|
+
|
|
101
107
|
doc
|
|
102
108
|
end
|
|
103
109
|
|
data/lib/swaggard/swagger/tag.rb
CHANGED
data/lib/swaggard/version.rb
CHANGED
data/lib/swaggard.rb
CHANGED
|
@@ -24,6 +24,7 @@ module Swaggard
|
|
|
24
24
|
def register_custom_yard_tags!
|
|
25
25
|
::YARD::Tags::Library.define_tag('Controller\'s tag', :tag)
|
|
26
26
|
::YARD::Tags::Library.define_tag('Operation id', :operation_id)
|
|
27
|
+
::YARD::Tags::Library.define_tag('Deprecated', :deprecated)
|
|
27
28
|
::YARD::Tags::Library.define_tag('Query parameter', :query_parameter)
|
|
28
29
|
::YARD::Tags::Library.define_tag('Form parameter', :form_parameter)
|
|
29
30
|
::YARD::Tags::Library.define_tag('Body required', :body_required)
|
|
@@ -48,6 +49,17 @@ module Swaggard
|
|
|
48
49
|
name.to_s.gsub('::', '.').gsub('#', '_')
|
|
49
50
|
end
|
|
50
51
|
|
|
52
|
+
RBS_COMMENT_LINE = /\A[:|]/
|
|
53
|
+
|
|
54
|
+
# A YARD docstring without the RBS inline type annotations (`#:` signatures
|
|
55
|
+
# and their `#|` continuation lines) when `ignore_rbs_comments` is enabled.
|
|
56
|
+
def docstring(yard_object)
|
|
57
|
+
text = yard_object.docstring.to_s
|
|
58
|
+
return text unless configuration.ignore_rbs_comments
|
|
59
|
+
|
|
60
|
+
text.lines.reject { |line| RBS_COMMENT_LINE.match?(line) }.join.strip
|
|
61
|
+
end
|
|
62
|
+
|
|
51
63
|
def get_doc(host = nil)
|
|
52
64
|
load!
|
|
53
65
|
|
data/spec/fixtures/api.json
CHANGED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
require 'spec_helper'
|
|
2
|
+
|
|
3
|
+
describe Swaggard::Swagger::Operation do
|
|
4
|
+
let(:source) do
|
|
5
|
+
<<~RUBY
|
|
6
|
+
class ThingsController
|
|
7
|
+
#: -> void
|
|
8
|
+
def undocumented; end
|
|
9
|
+
|
|
10
|
+
# List things
|
|
11
|
+
#
|
|
12
|
+
# Returns every thing
|
|
13
|
+
#: -> void
|
|
14
|
+
def rbs_below_yard; end
|
|
15
|
+
|
|
16
|
+
#: -> void
|
|
17
|
+
|
|
18
|
+
# Show a thing
|
|
19
|
+
#
|
|
20
|
+
# Returns one thing
|
|
21
|
+
def rbs_above_yard; end
|
|
22
|
+
|
|
23
|
+
# Update a thing
|
|
24
|
+
#
|
|
25
|
+
# Changes one thing
|
|
26
|
+
# @body_parameter [String] name The name
|
|
27
|
+
#: (
|
|
28
|
+
#| Integer id
|
|
29
|
+
#| ) -> void
|
|
30
|
+
def rbs_multiline(id); end
|
|
31
|
+
end
|
|
32
|
+
RUBY
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
let(:tag) { Struct.new(:name, :controller_class).new('Things', 'ThingsController') }
|
|
36
|
+
|
|
37
|
+
let(:original_ignore_rbs_comments) { Swaggard.configuration.ignore_rbs_comments }
|
|
38
|
+
|
|
39
|
+
before do
|
|
40
|
+
original_ignore_rbs_comments
|
|
41
|
+
Swaggard.register_custom_yard_tags!
|
|
42
|
+
::YARD::Registry.clear
|
|
43
|
+
::YARD.parse_string(source)
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
after do
|
|
47
|
+
::YARD::Registry.clear
|
|
48
|
+
Swaggard.configuration.ignore_rbs_comments = original_ignore_rbs_comments
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
def operation(name)
|
|
52
|
+
yard_object = ::YARD::Registry.at("ThingsController##{name}")
|
|
53
|
+
described_class.new(yard_object, tag, '/things', 'get', [])
|
|
54
|
+
end
|
|
55
|
+
|
|
56
|
+
it 'keeps RBS comments in the docs by default' do
|
|
57
|
+
expect(Swaggard.configuration.ignore_rbs_comments).to be(false)
|
|
58
|
+
expect(operation(:undocumented).summary).to eq(': -> void')
|
|
59
|
+
expect(operation(:rbs_below_yard).description).to eq("Returns every thing\n: -> void")
|
|
60
|
+
end
|
|
61
|
+
|
|
62
|
+
context 'when ignore_rbs_comments is enabled' do
|
|
63
|
+
before { Swaggard.configuration.ignore_rbs_comments = true }
|
|
64
|
+
|
|
65
|
+
it 'treats an action documented only by an RBS comment as undocumented' do
|
|
66
|
+
expect(operation(:undocumented)).to be_empty
|
|
67
|
+
end
|
|
68
|
+
|
|
69
|
+
it 'drops an RBS comment between the YARD block and the def' do
|
|
70
|
+
op = operation(:rbs_below_yard)
|
|
71
|
+
|
|
72
|
+
expect(op.summary).to eq('List things')
|
|
73
|
+
expect(op.description).to eq('Returns every thing')
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
it 'leaves a YARD block below a detached RBS comment unchanged' do
|
|
77
|
+
op = operation(:rbs_above_yard)
|
|
78
|
+
|
|
79
|
+
expect(op.summary).to eq('Show a thing')
|
|
80
|
+
expect(op.description).to eq('Returns one thing')
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
it 'drops a multi-line RBS signature and keeps the YARD tags' do
|
|
84
|
+
op = operation(:rbs_multiline)
|
|
85
|
+
|
|
86
|
+
expect(op.summary).to eq('Update a thing')
|
|
87
|
+
expect(op.description).to eq('Changes one thing')
|
|
88
|
+
body = op.definitions.fetch('ThingsController.rbs_multiline_body').to_doc({})
|
|
89
|
+
expect(body['properties']).to eq('name' => { 'type' => 'string', 'description' => 'The name' })
|
|
90
|
+
end
|
|
91
|
+
end
|
|
92
|
+
end
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: swaggard
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 4.
|
|
4
|
+
version: 4.3.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Adrian Gomez
|
|
@@ -156,7 +156,6 @@ files:
|
|
|
156
156
|
- spec/fixtures/dummy/config/application.rb
|
|
157
157
|
- spec/fixtures/dummy/config/environments/development.rb
|
|
158
158
|
- spec/fixtures/dummy/config/routes.rb
|
|
159
|
-
- spec/fixtures/dummy/log/development.log
|
|
160
159
|
- spec/fixtures/openapi_3_1_schema.json
|
|
161
160
|
- spec/fixtures/swagger_schema.json
|
|
162
161
|
- spec/integration/openapi_spec.rb
|
|
@@ -165,6 +164,7 @@ files:
|
|
|
165
164
|
- spec/swaggard/api_definition_spec.rb
|
|
166
165
|
- spec/swaggard/parsers/property_spec.rb
|
|
167
166
|
- spec/swaggard/swagger/definition_spec.rb
|
|
167
|
+
- spec/swaggard/swagger/operation_spec.rb
|
|
168
168
|
- spec/swaggard/swagger/parameters/body_spec.rb
|
|
169
169
|
- spec/swaggard/swagger/property_spec.rb
|
|
170
170
|
homepage: https://github.com/adrian-gomez/swaggard
|
|
@@ -198,7 +198,6 @@ test_files:
|
|
|
198
198
|
- spec/fixtures/dummy/config/application.rb
|
|
199
199
|
- spec/fixtures/dummy/config/environments/development.rb
|
|
200
200
|
- spec/fixtures/dummy/config/routes.rb
|
|
201
|
-
- spec/fixtures/dummy/log/development.log
|
|
202
201
|
- spec/fixtures/openapi_3_1_schema.json
|
|
203
202
|
- spec/fixtures/swagger_schema.json
|
|
204
203
|
- spec/integration/openapi_spec.rb
|
|
@@ -207,5 +206,6 @@ test_files:
|
|
|
207
206
|
- spec/swaggard/api_definition_spec.rb
|
|
208
207
|
- spec/swaggard/parsers/property_spec.rb
|
|
209
208
|
- spec/swaggard/swagger/definition_spec.rb
|
|
209
|
+
- spec/swaggard/swagger/operation_spec.rb
|
|
210
210
|
- spec/swaggard/swagger/parameters/body_spec.rb
|
|
211
211
|
- spec/swaggard/swagger/property_spec.rb
|
|
File without changes
|