swagger_yard 1.0.2 → 1.0.3
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 +21 -0
- data/lib/swagger_yard.rb +2 -0
- data/lib/swagger_yard/directives.rb +32 -0
- data/lib/swagger_yard/version.rb +1 -1
- metadata +4 -4
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 756c19df66b9851bc539daa6a77ba78b00814a73e514411c03ed036aaa0c2921
|
4
|
+
data.tar.gz: fa7b4ca209d1654df04d659f57c4e38803ce90c4c0a65d45c1aef7f19f655978
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: e00185e0b6e4d36c9933f3567b6223a7918ec47fe3a31f54a08d87442306efa3b6398a83cb820e4e04839f0b475102463963df580a75fd3918f974c014269993
|
7
|
+
data.tar.gz: ef4cdc1187050861e1bc4bfe6a23c223473e86def53ada9d65320c853a79e71c1d7ddcfb62eb9f9d69b5fab34a68f04503bda6f7825881a12021d9fb985d5e0f
|
data/README.md
CHANGED
@@ -41,6 +41,9 @@ Then start to annotate controllers and models as described below.
|
|
41
41
|
To generate a Swagger or OpenAPI specification, use one of the `SwaggerYard::Swagger` or `SwaggerYard::OpenAPI` classes as follows in a script or Rake task (or use [swagger_yard-rails](/livingsocial/swagger_yard-rails)):
|
42
42
|
|
43
43
|
```
|
44
|
+
# Register the yard tags
|
45
|
+
SwaggerYard.register_custom_yard_tags!
|
46
|
+
|
44
47
|
spec = SwaggerYard::OpenAPI.new
|
45
48
|
# Generate YAML
|
46
49
|
File.open("openapi.yml", "w") { |f| f << YAML.dump(spec.to_h) }
|
@@ -258,6 +261,24 @@ class Person
|
|
258
261
|
end
|
259
262
|
```
|
260
263
|
|
264
|
+
### Standalone Model ###
|
265
|
+
|
266
|
+
Types can be specified without being associated to an existing model with the `@!model` directive. It is useful when documenting a create and an update of the same class:
|
267
|
+
|
268
|
+
```ruby
|
269
|
+
# @!model CreatePet
|
270
|
+
# @property id(required) [integer]
|
271
|
+
# @property name(required) [string]
|
272
|
+
#
|
273
|
+
# @!model UpdatePet
|
274
|
+
# @property id(required) [integer]
|
275
|
+
# @property name [string]
|
276
|
+
```
|
277
|
+
|
278
|
+
It can also be needed when the body parameter of a path is not totally matching a model.
|
279
|
+
|
280
|
+
Note that a model name must be given to the directive.
|
281
|
+
|
261
282
|
|
262
283
|
### External Schema ###
|
263
284
|
|
data/lib/swagger_yard.rb
CHANGED
@@ -15,6 +15,7 @@ require "swagger_yard/path_item"
|
|
15
15
|
require "swagger_yard/swagger"
|
16
16
|
require "swagger_yard/openapi"
|
17
17
|
require "swagger_yard/handlers"
|
18
|
+
require "swagger_yard/directives"
|
18
19
|
|
19
20
|
module SwaggerYard
|
20
21
|
class Error < StandardError; end
|
@@ -115,6 +116,7 @@ module SwaggerYard
|
|
115
116
|
::YARD::Tags::Library.define_tag("Authorization Use", :authorize_with)
|
116
117
|
# @example is a core YARD tag, let's use it
|
117
118
|
# ::YARD::Tags::Library.define_tag("Example", :example, :with_title_and_text)
|
119
|
+
::YARD::Tags::Library.define_directive(:model, :with_title_and_text, Directives::ParamClassDirective)
|
118
120
|
end
|
119
121
|
end
|
120
122
|
end
|
@@ -0,0 +1,32 @@
|
|
1
|
+
module SwaggerYard::Directives
|
2
|
+
|
3
|
+
# A directive used to create a model tag with a dummy class.
|
4
|
+
# based on https://github.com/lsegal/yard/blob/master/lib/yard/tags/directives.rb#L361
|
5
|
+
class ParamClassDirective < YARD::Tags::Directive
|
6
|
+
|
7
|
+
def call; end
|
8
|
+
|
9
|
+
def after_parse
|
10
|
+
return unless handler
|
11
|
+
|
12
|
+
create_object
|
13
|
+
end
|
14
|
+
|
15
|
+
def create_object
|
16
|
+
name = tag.name
|
17
|
+
obj = YARD::CodeObjects::ClassObject.new(handler.namespace, tag.name)
|
18
|
+
handler.register_file_info(obj)
|
19
|
+
handler.register_source(obj)
|
20
|
+
handler.register_group(obj)
|
21
|
+
obj.docstring = YARD::Docstring.new!(parser.text,
|
22
|
+
parser.tags,
|
23
|
+
obj,
|
24
|
+
nil,
|
25
|
+
parser.reference)
|
26
|
+
obj.add_tag(YARD::Tags::Tag.new(:model, name))
|
27
|
+
parser.object = obj
|
28
|
+
parser.post_process
|
29
|
+
obj
|
30
|
+
end
|
31
|
+
end
|
32
|
+
end
|
data/lib/swagger_yard/version.rb
CHANGED
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: swagger_yard
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.0.
|
4
|
+
version: 1.0.3
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- chtrinh (Chris Trinh)
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date:
|
11
|
+
date: 2020-04-22 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: yard
|
@@ -193,6 +193,7 @@ files:
|
|
193
193
|
- lib/swagger_yard/api_group.rb
|
194
194
|
- lib/swagger_yard/authorization.rb
|
195
195
|
- lib/swagger_yard/configuration.rb
|
196
|
+
- lib/swagger_yard/directives.rb
|
196
197
|
- lib/swagger_yard/example.rb
|
197
198
|
- lib/swagger_yard/handlers.rb
|
198
199
|
- lib/swagger_yard/model.rb
|
@@ -227,8 +228,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
227
228
|
- !ruby/object:Gem::Version
|
228
229
|
version: '0'
|
229
230
|
requirements: []
|
230
|
-
|
231
|
-
rubygems_version: 2.7.4
|
231
|
+
rubygems_version: 3.0.3
|
232
232
|
signing_key:
|
233
233
|
specification_version: 4
|
234
234
|
summary: SwaggerYard API doc through YARD
|