r2-oas 0.1.0 → 0.1.2

Sign up to get free protection for your applications and to get access to all the features.
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.