swaggard 4.2.0 → 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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 22712f08a524289197fef03b0fa4b6e2f9b76bb998c78909ca0b8459a240b0fd
4
- data.tar.gz: c6002db5029e1013e0597a041dae4ce1ce03622e5245647bd9249d2524e5ccaf
3
+ metadata.gz: e58966e12de0580a4352f142f3dc5f76c75bef3366a81861acb1f7d5e1e7cf5b
4
+ data.tar.gz: af8536b1d6047dd86f57500cba80b15c14a3ef127c394cf188d61c627ecb8af8
5
5
  SHA512:
6
- metadata.gz: a4cc784c4e3f5e930e5be443bc3c026da984194087c939867eea961e77b5259b4ec84daef72802bfbb44519cf2da5fb2834bdacc7eaafdc62e94cf4a213b2ee3
7
- data.tar.gz: 06e9c4079d1dd6ae1f12a6bdd69b79279ae1d2481629e15a11b6beab3900fe1957f8b32b083951512a2dcc819eadbe6fe979b963ba177ba0b0f6bfc0bfab96e5
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,12 +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
- @summary = (yard_object.docstring.lines.first || '').chomp
19
+ docstring = Swaggard.docstring(yard_object)
20
+ @summary = (docstring.lines.first || '').chomp
20
21
  @parameters = []
21
22
  @responses = []
22
23
  @deprecated = false
23
24
 
24
- @description = (yard_object.docstring.lines[1..-1] || []).map(&:chomp).reject(&:empty?).compact.join("\n")
25
+ @description = (docstring.lines[1..-1] || []).map(&:chomp).reject(&:empty?).compact.join("\n")
25
26
  @http_method = verb
26
27
  @path = path
27
28
 
@@ -15,7 +15,7 @@ module Swaggard
15
15
  @name = tag ? tag.text : "#{@controller_class.controller_path}"
16
16
  @name, @route = @name.split(' ')
17
17
 
18
- @description = yard_object.docstring || ''
18
+ @description = Swaggard.docstring(yard_object)
19
19
  end
20
20
 
21
21
  def to_doc
@@ -1,3 +1,3 @@
1
1
  module Swaggard
2
- VERSION = '4.2.0'
2
+ VERSION = '4.3.0'
3
3
  end
data/lib/swaggard.rb CHANGED
@@ -49,6 +49,17 @@ module Swaggard
49
49
  name.to_s.gsub('::', '.').gsub('#', '_')
50
50
  end
51
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
+
52
63
  def get_doc(host = nil)
53
64
  load!
54
65
 
@@ -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.2.0
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