r2-oas 0.1.0 → 0.1.2
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/CHANGELOG.md +13 -1
- data/Gemfile.lock +85 -70
- data/README.ja.md +11 -413
- data/README.md +9 -409
- data/docs/.nojekyll +0 -0
- data/docs/README.md +326 -0
- data/docs/_sidebar.md +22 -0
- data/docs/index.html +28 -0
- data/docs/{versions/v3.md → schema/3.0.0.md} +1 -1
- data/docs/setting/COC.md +14 -0
- data/docs/setting/CORS.md +22 -0
- data/docs/setting/configure.md +163 -0
- data/docs/{HOW_TO_ANALYZE_DOCS.md → usage/analyze_docs.md} +8 -8
- data/docs/usage/clean_docs.md +19 -0
- data/docs/{HOW_TO_DEPLOY_SWAGGER_DOC.md → usage/deploy_docs.md} +8 -8
- data/docs/{HOW_TO_DISPLAY_PATHS_LIST.md → usage/display_paths_list.md} +15 -8
- data/docs/{HOW_TO_DISPLAY_PATHS_STATS.md → usage/display_paths_stats.md} +15 -14
- data/docs/{HOW_TO_START_SWAGGER_EDITOR.md → usage/edit_docs.md} +10 -10
- data/docs/{HOW_TO_GENERATE_DOCS.md → usage/generate_docs.md} +9 -9
- data/docs/{HOW_TO_MONITOR_SWAGGER_DOC.md → usage/monitor_docs.md} +9 -9
- data/docs/usage/use_hook_methods.md +236 -0
- data/docs/{HOW_TO_USE_HOOK_WHEN_GENERATE_DOC.md → usage/use_hook_to_generate_docs.md} +6 -15
- data/docs/{HOW_TO_USE_SCHEMA_NAMESPACE.md → usage/use_schema_namespace.md} +16 -9
- data/docs/{HOW_TO_USE_TAG_NAMESPACE.md → usage/use_tag_namespace.md} +22 -16
- data/docs/{HOW_TO_START_SWAGGER_UI.md → usage/view_docs.md} +10 -10
- data/lib/r2-oas/app_configuration.rb +19 -16
- data/lib/r2-oas/deploy/client.rb +1 -1
- data/lib/r2-oas/schema/v3/object/path_item_object.rb +17 -9
- data/lib/r2-oas/version.rb +1 -1
- data/r2-oas.gemspec +5 -19
- metadata +42 -46
- data/docs/HOW_TO_CLEAN_DOCS.md +0 -19
@@ -1,17 +1,17 @@
|
|
1
|
-
|
1
|
+
# Analyze docs
|
2
2
|
|
3
|
-
|
3
|
+
## Prepare
|
4
4
|
|
5
|
-
|
5
|
+
Add this line to your application's Gemfile:
|
6
6
|
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
config.schema_save_dir_name = "src"
|
11
|
-
config.doc_save_file_name = "oas_doc.yml"
|
7
|
+
```ruby
|
8
|
+
group :development do
|
9
|
+
gem 'r2-oas'
|
12
10
|
end
|
13
11
|
```
|
14
12
|
|
13
|
+
## Command
|
14
|
+
|
15
15
|
```bash
|
16
16
|
$ OAS_FILE="~/Desktop/swagger_file.yml" bundle exec rake routes:oas:analyze
|
17
17
|
```
|
@@ -0,0 +1,19 @@
|
|
1
|
+
# Clean docs
|
2
|
+
|
3
|
+
Delete `components/schemas` and `components/requestBodies` files not in use.
|
4
|
+
|
5
|
+
## Prepare
|
6
|
+
|
7
|
+
Add this line to your application's Gemfile:
|
8
|
+
|
9
|
+
```ruby
|
10
|
+
group :development do
|
11
|
+
gem 'r2-oas'
|
12
|
+
end
|
13
|
+
```
|
14
|
+
|
15
|
+
## Command
|
16
|
+
|
17
|
+
```bash
|
18
|
+
$ bundle exec rake routes:oas:clean
|
19
|
+
```
|
@@ -1,17 +1,17 @@
|
|
1
|
-
|
1
|
+
# Deploy docs
|
2
2
|
|
3
|
-
|
3
|
+
## Prepare
|
4
4
|
|
5
|
-
|
5
|
+
Add this line to your application's Gemfile:
|
6
6
|
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
config.schema_save_dir_name = "src"
|
11
|
-
config.doc_save_file_name = "oas_doc.yml"
|
7
|
+
```ruby
|
8
|
+
group :development do
|
9
|
+
gem 'r2-oas'
|
12
10
|
end
|
13
11
|
```
|
14
12
|
|
13
|
+
## Command
|
14
|
+
|
15
15
|
```bash
|
16
16
|
$ bundle exec rake routes:oas:deploy
|
17
17
|
```
|
@@ -1,17 +1,24 @@
|
|
1
|
-
## Basic Usage
|
2
1
|
|
3
|
-
|
2
|
+
# Display paths list
|
3
|
+
|
4
|
+
## Prepare
|
4
5
|
|
5
|
-
|
6
|
+
Add this line to your application's Gemfile:
|
6
7
|
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
config.schema_save_dir_name = "src"
|
11
|
-
config.doc_save_file_name = "oas_doc.yml"
|
8
|
+
```ruby
|
9
|
+
group :development do
|
10
|
+
gem 'r2-oas'
|
12
11
|
end
|
13
12
|
```
|
14
13
|
|
14
|
+
## Comamnd
|
15
|
+
|
16
|
+
```
|
17
|
+
$ bundle exec rake routes:oas:paths_ls
|
18
|
+
```
|
19
|
+
|
20
|
+
## Example
|
21
|
+
|
15
22
|
```bash
|
16
23
|
$ bundle exec rake routes:oas:paths_ls
|
17
24
|
/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/user.yml
|
@@ -1,24 +1,25 @@
|
|
1
|
-
## Basic Usage
|
2
1
|
|
3
|
-
|
2
|
+
# Display paths stats
|
4
3
|
|
5
|
-
|
4
|
+
## Prepare
|
6
5
|
|
7
|
-
|
8
|
-
# default setting
|
9
|
-
config.root_dir_path = "./oas_docs"
|
10
|
-
config.schema_save_dir_name = "src"
|
11
|
-
config.doc_save_file_name = "oas_doc.yml"
|
6
|
+
Add this line to your application's Gemfile:
|
12
7
|
|
13
|
-
|
14
|
-
|
15
|
-
|
16
|
-
paths_stats.table_title_color = :yellow
|
17
|
-
paths_stats.heading_color = :yellow
|
18
|
-
end
|
8
|
+
```ruby
|
9
|
+
group :development do
|
10
|
+
gem 'r2-oas'
|
19
11
|
end
|
20
12
|
```
|
21
13
|
|
14
|
+
## Command
|
15
|
+
|
16
|
+
```bash
|
17
|
+
$ bundle exec rake routes:oas:paths_stats
|
18
|
+
```
|
19
|
+
|
20
|
+
## Example
|
21
|
+
|
22
|
+
|
22
23
|
```bash
|
23
24
|
$ bundle exec rake routes:oas:paths_stats
|
24
25
|
+----+--------------------------------------------------------+---------------------------+---------------------------+
|
@@ -1,17 +1,17 @@
|
|
1
|
-
|
1
|
+
# Edit docs
|
2
2
|
|
3
|
-
|
3
|
+
## Prepare
|
4
4
|
|
5
|
-
|
5
|
+
Add this line to your application's Gemfile:
|
6
6
|
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
config.schema_save_dir_name = "src"
|
11
|
-
config.doc_save_file_name = "oas_doc.yml"
|
7
|
+
```ruby
|
8
|
+
group :development do
|
9
|
+
gem 'r2-oas'
|
12
10
|
end
|
13
11
|
```
|
14
12
|
|
13
|
+
## Command
|
14
|
+
|
15
15
|
```bash
|
16
16
|
$ bundle exec rake routes:oas:editor
|
17
17
|
```
|
@@ -155,10 +155,10 @@ container id: 1a9752d2702045b2fde587dda3ce064233a735165f9b70bc6f86e603abfe3a39 r
|
|
155
155
|
I, [2019-04-07T19:43:53.666565 #33493] INFO -- : [R2-OAS] end
|
156
156
|
```
|
157
157
|
|
158
|
-
##
|
158
|
+
## Use PATHS_FILE environment
|
159
159
|
|
160
160
|
If you want to generate docs by squeezing unit paths (For example, `api/v1/task.yml`),
|
161
|
-
you set PATHS_FILE environment like this:
|
161
|
+
you set `PATHS_FILE` environment like this:
|
162
162
|
|
163
163
|
```bash
|
164
164
|
$ PATHS_FILE="../oas_docs/schema/paths/api/v1/task.yml" bundle exec rake routes:oas:editor
|
@@ -1,17 +1,17 @@
|
|
1
|
-
|
1
|
+
# Generate docs
|
2
2
|
|
3
|
-
|
3
|
+
## Prepare
|
4
4
|
|
5
|
-
|
5
|
+
Add this line to your application's Gemfile:
|
6
6
|
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
config.schema_save_dir_name = "src"
|
11
|
-
config.doc_save_file_name = "oas_doc.yml"
|
7
|
+
```ruby
|
8
|
+
group :development do
|
9
|
+
gem 'r2-oas'
|
12
10
|
end
|
13
11
|
```
|
14
12
|
|
13
|
+
## Command
|
14
|
+
|
15
15
|
```bash
|
16
16
|
$ bundle exec rake routes:oas:docs
|
17
17
|
```
|
@@ -209,7 +209,7 @@ oas_docs
|
|
209
209
|
## Advanced Usage
|
210
210
|
|
211
211
|
If you want to generate docs by squeezing unit paths (For example, `api/v1/task.yml`),
|
212
|
-
you set PATHS_FILE environment like this:
|
212
|
+
you set `PATHS_FILE` environment like this:
|
213
213
|
|
214
214
|
```bash
|
215
215
|
$ PATHS_FILE="../oas_docs/schema/paths/api/v1/task.yml" bundle exec rake routes:oas:docs
|
@@ -1,17 +1,17 @@
|
|
1
|
-
|
1
|
+
# Monitor docs
|
2
2
|
|
3
|
-
|
3
|
+
## Prepare
|
4
4
|
|
5
|
-
|
5
|
+
Add this line to your application's Gemfile:
|
6
6
|
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
config.schema_save_dir_name = "src"
|
11
|
-
config.doc_save_file_name = "oas_doc.yml"
|
7
|
+
```ruby
|
8
|
+
group :development do
|
9
|
+
gem 'r2-oas'
|
12
10
|
end
|
13
11
|
```
|
14
12
|
|
13
|
+
## Command
|
14
|
+
|
15
15
|
```bash
|
16
16
|
$ bundle exec rake routes:oas:monitor
|
17
17
|
```
|
@@ -137,7 +137,7 @@ bulk_action POST /:model_name/bulk_action(.:format) rails_admin/main#
|
|
137
137
|
show_in_app GET /:model_name/:id/show_in_app(.:format) rails_admin/main#show_in_app
|
138
138
|
```
|
139
139
|
|
140
|
-
####
|
140
|
+
#### VS Code
|
141
141
|
|
142
142
|
If you use [Swagger Viewer](https://marketplace.visualstudio.com/items?itemName=Arjun.swagger-viewer)
|
143
143
|
|
@@ -0,0 +1,236 @@
|
|
1
|
+
# Use hook methods
|
2
|
+
|
3
|
+
Supported hook(life cycle methods) is like this:
|
4
|
+
|
5
|
+
- `before_create`
|
6
|
+
- `after_create`
|
7
|
+
|
8
|
+
Supported Hook class is like this:
|
9
|
+
|
10
|
+
- `R2OAS::Schema::V3::InfoObject`
|
11
|
+
- `R2OAS::Schema::V3::PathsObject`
|
12
|
+
- `R2OAS::Schema::V3::PathItemObject`
|
13
|
+
- `R2OAS::Schema::V3::ExternalDocumentObject`
|
14
|
+
- `R2OAS::Schema::V3::ComponentsObject`
|
15
|
+
- `R2OAS::Schema::V3::Components::SchemaObject`
|
16
|
+
- `R2OAS::Schema::V3::Components::RequestBodyObject`
|
17
|
+
|
18
|
+
By inheriting these classes, you can hook them at the time of document generation by writing like this:
|
19
|
+
|
20
|
+
#### case: InfoObject
|
21
|
+
|
22
|
+
```ruby
|
23
|
+
class CustomInfoObject < R2OAS::Schema::V3::InfoObject
|
24
|
+
before_create do |doc|
|
25
|
+
# [Important] Please change doc destructively.
|
26
|
+
# [Important] To be able to use methods in Rails !
|
27
|
+
doc.merge!({
|
28
|
+
# Something ....
|
29
|
+
})
|
30
|
+
end
|
31
|
+
|
32
|
+
after_create do |doc, path|
|
33
|
+
# [Important] Please change doc destructively.
|
34
|
+
# [Important] To be able to use methods in Rails !
|
35
|
+
doc.merge!({
|
36
|
+
# Something ....
|
37
|
+
})
|
38
|
+
end
|
39
|
+
end
|
40
|
+
```
|
41
|
+
|
42
|
+
#### case: PathsObject
|
43
|
+
|
44
|
+
```ruby
|
45
|
+
class CustomPathsObject < R2OAS::Schema::V3::PathsObject
|
46
|
+
before_create do |doc|
|
47
|
+
# [Important] Please change doc destructively.
|
48
|
+
# [Important] To be able to use methods in Rails !
|
49
|
+
doc.merge!({
|
50
|
+
# Something ....
|
51
|
+
})
|
52
|
+
end
|
53
|
+
|
54
|
+
after_create do |doc|
|
55
|
+
# [Important] Please change doc destructively.
|
56
|
+
# [Important] To be able to use methods in Rails !
|
57
|
+
doc.merge!({
|
58
|
+
# Something ....
|
59
|
+
})
|
60
|
+
end
|
61
|
+
end
|
62
|
+
```
|
63
|
+
|
64
|
+
#### case: PathItemObject
|
65
|
+
|
66
|
+
```ruby
|
67
|
+
class CustomPathItemObject < R2OAS::Schema::V3::PathItemObject
|
68
|
+
before_create do |doc, path|
|
69
|
+
# [Important] Please change doc destructively.
|
70
|
+
# [Important] To be able to use methods in Rails !
|
71
|
+
doc.merge!({
|
72
|
+
# Something ....
|
73
|
+
})
|
74
|
+
end
|
75
|
+
|
76
|
+
after_create do |doc, schema_name|
|
77
|
+
# [Important] Please change doc destructively.
|
78
|
+
# [Important] To be able to use methods in Rails !
|
79
|
+
doc.merge!({
|
80
|
+
# Something ....
|
81
|
+
})
|
82
|
+
end
|
83
|
+
end
|
84
|
+
```
|
85
|
+
|
86
|
+
#### case: ExternalDocumentObject
|
87
|
+
|
88
|
+
```ruby
|
89
|
+
class CustomExternalDocumentObject < R2OAS::Schema::V3::ExternalDocumentObject
|
90
|
+
before_create do |doc|
|
91
|
+
# [Important] Please change doc destructively.
|
92
|
+
# [Important] To be able to use methods in Rails !
|
93
|
+
doc.merge!({
|
94
|
+
# Something ....
|
95
|
+
})
|
96
|
+
end
|
97
|
+
|
98
|
+
after_create do |doc|
|
99
|
+
# [Important] Please change doc destructively.
|
100
|
+
# [Important] To be able to use methods in Rails !
|
101
|
+
doc.merge!({
|
102
|
+
# Something ....
|
103
|
+
})
|
104
|
+
end
|
105
|
+
end
|
106
|
+
```
|
107
|
+
|
108
|
+
#### case: ComponentsObject
|
109
|
+
|
110
|
+
```ruby
|
111
|
+
class CustomComponentsObject < R2OAS::Schema::V3::ComponentsObject
|
112
|
+
before_create do |doc|
|
113
|
+
# [Important] Please change doc destructively.
|
114
|
+
# [Important] To be able to use methods in Rails !
|
115
|
+
doc.merge!({
|
116
|
+
# Something ....
|
117
|
+
})
|
118
|
+
end
|
119
|
+
|
120
|
+
after_create do |doc|
|
121
|
+
# [Important] Please change doc destructively.
|
122
|
+
# [Important] To be able to use methods in Rails !
|
123
|
+
doc.merge!({
|
124
|
+
# Something ....
|
125
|
+
})
|
126
|
+
end
|
127
|
+
end
|
128
|
+
```
|
129
|
+
|
130
|
+
#### case: Components::SchemaObject
|
131
|
+
|
132
|
+
```ruby
|
133
|
+
class CustomComponentsSchemaObject < R2OAS::Schema::V3::Components::SchemaObject
|
134
|
+
before_create do |doc, schema_name|
|
135
|
+
# [Important] Please change doc destructively.
|
136
|
+
# [Important] To be able to use methods in Rails !
|
137
|
+
doc.merge!({
|
138
|
+
# Something ....
|
139
|
+
})
|
140
|
+
end
|
141
|
+
|
142
|
+
after_create do |doc, schema_name|
|
143
|
+
# [Important] Please change doc destructively.
|
144
|
+
# [Important] To be able to use methods in Rails !
|
145
|
+
doc.merge!({
|
146
|
+
# Something ....
|
147
|
+
})
|
148
|
+
end
|
149
|
+
end
|
150
|
+
```
|
151
|
+
|
152
|
+
If you want to determine the component schema name at runtime, like this:
|
153
|
+
|
154
|
+
```ruby
|
155
|
+
class CustomComponentsSchemaObject < R2OAS::Schema::V3::Components::SchemaObject
|
156
|
+
def components_schema_name(doc, path_component, tag_name, verb, http_status, schema_name)
|
157
|
+
# [Important] Please return string.
|
158
|
+
# default
|
159
|
+
schema_name
|
160
|
+
end
|
161
|
+
end
|
162
|
+
```
|
163
|
+
|
164
|
+
`path_component` is `R2OAS::Routing::PathComponent` instance.
|
165
|
+
|
166
|
+
```ruby
|
167
|
+
module R2OAS
|
168
|
+
module Routing
|
169
|
+
class PathComponent < BaseComponent
|
170
|
+
def initialize(path)
|
171
|
+
def to_s
|
172
|
+
def symbol_to_brace
|
173
|
+
def path_parameters_data
|
174
|
+
def path_excluded_path_parameters
|
175
|
+
def exist_path_parameters?
|
176
|
+
def path_parameters
|
177
|
+
private
|
178
|
+
def without_format
|
179
|
+
```
|
180
|
+
|
181
|
+
#### case: Components::RequestBodyObject
|
182
|
+
|
183
|
+
```ruby
|
184
|
+
class CustomComponentsRequestBodyObject < R2OAS::Schema::V3::Components::RequestBodyObject
|
185
|
+
before_create do |doc, schema_name|
|
186
|
+
# [Important] Please change doc destructively.
|
187
|
+
# [Important] To be able to use methods in Rails !
|
188
|
+
doc.merge!({
|
189
|
+
# Something ....
|
190
|
+
})
|
191
|
+
end
|
192
|
+
|
193
|
+
after_create do |doc, schema_name|
|
194
|
+
# [Important] Please change doc destructively.
|
195
|
+
# [Important] To be able to use methods in Rails !
|
196
|
+
doc.merge!({
|
197
|
+
# Something ....
|
198
|
+
})
|
199
|
+
end
|
200
|
+
end
|
201
|
+
```
|
202
|
+
|
203
|
+
If you want to determine the component schema name at runtime, like this:
|
204
|
+
|
205
|
+
```ruby
|
206
|
+
class CustomComponentsRequestBodyObject < R2OAS::Schema::V3::Components::RequestBodyObject
|
207
|
+
def components_request_body_name(doc, path_component, tag_name, verb, schema_name)
|
208
|
+
# [Important] Please return string.
|
209
|
+
# default
|
210
|
+
schema_name
|
211
|
+
end
|
212
|
+
|
213
|
+
def components_schema_name(doc, path_component, tag_name, verb, schema_name)
|
214
|
+
# [Important] Please return string.
|
215
|
+
# default
|
216
|
+
schema_name
|
217
|
+
end
|
218
|
+
end
|
219
|
+
```
|
220
|
+
|
221
|
+
And write this to the configuration.
|
222
|
+
|
223
|
+
```ruby
|
224
|
+
# If only InfoObject and PathItemObject, use a custom class
|
225
|
+
R2OAS.configure do |config|
|
226
|
+
#
|
227
|
+
# omission ...
|
228
|
+
#
|
229
|
+
config.use_object_classes.merge!({
|
230
|
+
info_object: CustomInfoObject,
|
231
|
+
path_item_object: CustomPathItemObject
|
232
|
+
})
|
233
|
+
end
|
234
|
+
```
|
235
|
+
|
236
|
+
This is the end.
|