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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 0f81d2b18d49097affa50030384f9ba3ca7a53ddd363952f2496bf77496eee5d
4
- data.tar.gz: fc112e57ff31fcf3a699543054c97d4a3204113acfca9014c9133d0a5acd5ee3
3
+ metadata.gz: e58966e12de0580a4352f142f3dc5f76c75bef3366a81861acb1f7d5e1e7cf5b
4
+ data.tar.gz: af8536b1d6047dd86f57500cba80b15c14a3ef127c394cf188d61c627ecb8af8
5
5
  SHA512:
6
- metadata.gz: 503363ed15e0b78f38e56cee37a40c5ff06810be7b7cfd6886aa1fa6eedd9dd2724e00f3ae4f756c03995ef832e16ab146fd4bd9e700a7c8de57e0ab8fbcc846
7
- data.tar.gz: 3459ce52d39b49c4d12036a4cd1fa01f019b08ba5572d66cd619909369487e9109a1cdd84caf223c7ca93df01f2e03636dd18ade95bf7a8cd544b77c3128170d
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
- @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 = []
23
+ @deprecated = false
22
24
 
23
- @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")
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
 
@@ -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.1.1'
2
+ VERSION = '4.3.0'
3
3
  end
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
 
@@ -80,7 +80,8 @@
80
80
  }
81
81
  }
82
82
  }
83
- }
83
+ },
84
+ "deprecated": true
84
85
  }
85
86
  },
86
87
  "/pets/{id}": {
@@ -15,6 +15,7 @@ class PetsController < ApplicationController
15
15
 
16
16
  # create a new Pet
17
17
  #
18
+ # @deprecated
18
19
  # @body_required
19
20
  # @body_definition PetBody
20
21
  def create
@@ -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.1.1
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