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.
Files changed (33) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +13 -1
  3. data/Gemfile.lock +85 -70
  4. data/README.ja.md +11 -413
  5. data/README.md +9 -409
  6. data/docs/.nojekyll +0 -0
  7. data/docs/README.md +326 -0
  8. data/docs/_sidebar.md +22 -0
  9. data/docs/index.html +28 -0
  10. data/docs/{versions/v3.md → schema/3.0.0.md} +1 -1
  11. data/docs/setting/COC.md +14 -0
  12. data/docs/setting/CORS.md +22 -0
  13. data/docs/setting/configure.md +163 -0
  14. data/docs/{HOW_TO_ANALYZE_DOCS.md → usage/analyze_docs.md} +8 -8
  15. data/docs/usage/clean_docs.md +19 -0
  16. data/docs/{HOW_TO_DEPLOY_SWAGGER_DOC.md → usage/deploy_docs.md} +8 -8
  17. data/docs/{HOW_TO_DISPLAY_PATHS_LIST.md → usage/display_paths_list.md} +15 -8
  18. data/docs/{HOW_TO_DISPLAY_PATHS_STATS.md → usage/display_paths_stats.md} +15 -14
  19. data/docs/{HOW_TO_START_SWAGGER_EDITOR.md → usage/edit_docs.md} +10 -10
  20. data/docs/{HOW_TO_GENERATE_DOCS.md → usage/generate_docs.md} +9 -9
  21. data/docs/{HOW_TO_MONITOR_SWAGGER_DOC.md → usage/monitor_docs.md} +9 -9
  22. data/docs/usage/use_hook_methods.md +236 -0
  23. data/docs/{HOW_TO_USE_HOOK_WHEN_GENERATE_DOC.md → usage/use_hook_to_generate_docs.md} +6 -15
  24. data/docs/{HOW_TO_USE_SCHEMA_NAMESPACE.md → usage/use_schema_namespace.md} +16 -9
  25. data/docs/{HOW_TO_USE_TAG_NAMESPACE.md → usage/use_tag_namespace.md} +22 -16
  26. data/docs/{HOW_TO_START_SWAGGER_UI.md → usage/view_docs.md} +10 -10
  27. data/lib/r2-oas/app_configuration.rb +19 -16
  28. data/lib/r2-oas/deploy/client.rb +1 -1
  29. data/lib/r2-oas/schema/v3/object/path_item_object.rb +17 -9
  30. data/lib/r2-oas/version.rb +1 -1
  31. data/r2-oas.gemspec +5 -19
  32. metadata +42 -46
  33. data/docs/HOW_TO_CLEAN_DOCS.md +0 -19
@@ -1,17 +1,17 @@
1
- ## Basic Usage
1
+ # Analyze docs
2
2
 
3
- ```ruby
3
+ ## Prepare
4
4
 
5
- require 'r2-oas'
5
+ Add this line to your application's Gemfile:
6
6
 
7
- R2OAS.configure do |config|
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"
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
- ## Basic Usage
1
+ # Deploy docs
2
2
 
3
- ```ruby
3
+ ## Prepare
4
4
 
5
- require 'r2-oas'
5
+ Add this line to your application's Gemfile:
6
6
 
7
- R2OAS.configure do |config|
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"
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
- ```ruby
2
+ # Display paths list
3
+
4
+ ## Prepare
4
5
 
5
- require 'r2-oas'
6
+ Add this line to your application's Gemfile:
6
7
 
7
- R2OAS.configure do |config|
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"
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
- ```ruby
2
+ # Display paths stats
4
3
 
5
- require 'r2-oas'
4
+ ## Prepare
6
5
 
7
- R2OAS.configure do |config|
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
- config.tool.paths_stats.configure do |paths_stats|
14
- paths_stats.month_to_turn_to_warning_color = 3
15
- paths_stats.warning_color = :red
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
- ## Basic Usage
1
+ # Edit docs
2
2
 
3
- ```ruby
3
+ ## Prepare
4
4
 
5
- require 'r2-oas'
5
+ Add this line to your application's Gemfile:
6
6
 
7
- R2OAS.configure do |config|
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"
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
- ## Advanced Usage
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
- ## Basic Usage
1
+ # Generate docs
2
2
 
3
- ```ruby
3
+ ## Prepare
4
4
 
5
- require 'r2-oas'
5
+ Add this line to your application's Gemfile:
6
6
 
7
- R2OAS.configure do |config|
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"
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
- ## Basic Usage
1
+ # Monitor docs
2
2
 
3
- ```ruby
3
+ ## Prepare
4
4
 
5
- require 'r2-oas'
5
+ Add this line to your application's Gemfile:
6
6
 
7
- R2OAS.configure do |config|
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"
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
- #### Usage
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.