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
data/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![Coverage Status](https://coveralls.io/repos/github/yukihirop/r2-oas/badge.svg)](https://coveralls.io/github/yukihirop/r2-oas)
5
5
  [![Maintainability](https://api.codeclimate.com/v1/badges/f8c3846f350bb412fd63/maintainability)](https://codeclimate.com/github/yukihirop/r2-oas/maintainability)
6
6
 
7
- Generate api docment(OpenAPI) side only from `rails` routing.
7
+ Generate api docment(OpenAPI) side only from `Rails` routing.
8
8
 
9
9
  Provides a rake command to help `generate` , `view` , and `edit` OpenAPI documents.
10
10
 
@@ -62,88 +62,7 @@ bundle exec routes:oas:docs
62
62
  bundle exec routes:oas:editor
63
63
  ```
64
64
 
65
- ## 📖 Usage
66
-
67
- All settings are optional. The initial value is as follows.
68
-
69
- In your rails project, Write `config/environments/development.rb` like that:
70
-
71
- ```ruby
72
- # default setting
73
- R2OAS.configure do |config|
74
- config.version = :v3
75
- config.root_dir_path = "./oas_docs"
76
- config.schema_save_dir_name = "src"
77
- config.doc_save_file_name = "oas_doc.yml"
78
- config.force_update_schema = false
79
- config.use_tag_namespace = true
80
- config.use_schema_namespace = false
81
- config.interval_to_save_edited_tmp_schema = 15
82
- # :dot or :underbar
83
- config.namespace_type = :underbar
84
- config.deploy_dir_path = "./deploy_docs"
85
-
86
- config.server.data = [
87
- {
88
- url: "http://localhost:3000",
89
- description: "localhost"
90
- }
91
- ]
92
-
93
- config.swagger.configure do |swagger|
94
- swagger.ui.image = "swaggerapi/swagger-ui"
95
- swagger.ui.port = "8080"
96
- swagger.ui.exposed_port = "8080/tcp"
97
- swagger.ui.volume = "/app/swagger.json"
98
- swagger.editor.image = "swaggerapi/swagger-editor"
99
- swagger.editor.port = "81"
100
- swagger.editor.exposed_port = "8080/tcp"
101
- end
102
-
103
- config.use_object_classes = {
104
- info_object: R2OAS::Schema::V3::InfoObject,
105
- paths_object: R2OAS::Schema::V3::PathsObject,
106
- path_item_object: R2OAS::Schema::V3::PathItemObject,
107
- external_document_object: R2OAS::Schema::V3::ExternalDocumentObject,
108
- components_object: R2OAS::Schema::V3::ComponentsObject,
109
- components_schema_object: R2OAS::Schema::V3::Components::SchemaObject,
110
- components_request_body_object: R2OAS::Schema::V3::Components::RequestBodyObject
111
- }
112
-
113
- config.http_statuses_when_http_method = {
114
- get: {
115
- default: %w(200 422),
116
- path_parameter: %w(200 404 422)
117
- },
118
- post: {
119
- default: %w(201 422),
120
- path_parameter: %w(201 404 422)
121
- },
122
- patch: {
123
- default: %w(204 422),
124
- path_parameter: %w(204 404 422)
125
- },
126
- put: {
127
- default: %w(204 422),
128
- path_parameter: %w(204 404 422)
129
- },
130
- delete: {
131
- default: %w(200 422),
132
- path_parameter: %w(200 404 422)
133
- }
134
- }
135
-
136
- config.http_methods_when_generate_request_body = %w[post patch put]
137
-
138
- config.tool.paths_stats.configure do |paths_stats|
139
- paths_stats.month_to_turn_to_warning_color = 3
140
- paths_stats.warning_color = :red
141
- paths_stats.table_title_color = :yellow
142
- paths_stats.heading_color = :yellow
143
- paths_stats.highlight_color = :magenta
144
- end
145
- end
146
- ```
65
+ ## Usage
147
66
 
148
67
  You can execute the following command in the root directory of rails.
149
68
 
@@ -179,20 +98,9 @@ $ bundle exec rake routes:oas:paths_ls
179
98
  $ bundle exec rake routes:oas:paths_stats
180
99
  ```
181
100
 
182
- ## 📚 More Usage
183
-
184
- - [How to generate docs](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_GENERATE_DOCS.md)
185
- - [How to start swagger editor](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_START_SWAGGER_EDITOR.md)
186
- - [How to start swagger ui](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_START_SWAGGER_UI.md)
187
- - [How to monitor swagger document](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_MONITOR_SWAGGER_DOC.md)
188
- - [How to analyze docs](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_ANALYZE_DOCS.md)
189
- - [How to clean docs](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_CLEAN_DOCS.md)
190
- - [How to deploy swagger doc](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_DEPLOY_SWAGGER_DOC.md)
191
- - [How to use tag namespace](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_USE_TAG_NAMESPACE.md)
192
- - [How to use schema namespace](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_USE_SCHEMA_NAMESPACE.md)
193
- - [How to use hook when generate doc](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_USE_HOOK_WHEN_GENERATE_DOC.md)
194
- - [How to display paths list](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_DISPLAY_PATHS_LIST.md)
195
- - [How to display paths stats](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_DISPLAY_PATHS_STATS.md)
101
+ ## 📚 Documents
102
+
103
+ Full docs are available at https://yukihirop.github.io/r2-oas
196
104
 
197
105
  ## ❤️ Support Rails Version
198
106
 
@@ -209,9 +117,7 @@ $ bundle exec rake routes:oas:paths_stats
209
117
 
210
118
  ## ❤️ Support OpenAPI Schema
211
119
 
212
- |version|document|
213
- |-------|--------|
214
- |v3|[versions/v3.md](https://github.com/yukihirop/r2-oas/blob/master/docs/versions/v3.md)|
120
+ Full docs are available at https://yukihirop.github.io/r2-oas/#/schema/3.0.0
215
121
 
216
122
  ## ❗️ Convention over Configuration (CoC)
217
123
 
@@ -230,321 +136,15 @@ $ bundle exec rake routes:oas:paths_stats
230
136
 
231
137
  ## ⚙ Configure
232
138
 
233
- we explain the options that can be set.
234
-
235
- #### basic
236
-
237
- |option|description|default|
238
- |------|-----------|---|
239
- |version|OpenAPI schema version| `:v3` |
240
- |root_dir_path|Root directory for storing products.| `"./oas_docs"` |
241
- |schema_save_dir_name|Directory name for storing swagger schemas|`"src"`|
242
- |doc_save_file_name|File name for storing swagger doc|`"oas_doc.yml"`|
243
- |force_update_schema|Force update schema from routes data|`false`|
244
- |use_tag_namespace|Use namespace for tag name|`true`|
245
- |use_schema_namespace|Use namespace for schema name|`true`|
246
- |interval_to_save_edited_tmp_schema|Interval(sec) to save edited tmp schema|`15`|
247
- |http_statuses_when_http_method|Determine the response to support for each HTTP method|omission...|
248
- |http_methods_when_generate_request_body|HTTP methods when generate requestBody|`[post put patch]`|
249
- |namespace_type|namespace for components(schemas/requestBodies) name| `underbar` |
250
- |deploy_dir_path|deploy directory.|`"./deploy_docs"`|
251
-
252
- #### server
253
-
254
- |option|children option|description|default|
255
- |------|---------------|-----------|-------|
256
- |server|data|Server data (url, description) |[{ url: `http://localhost:3000`, description: `localhost` }] |
257
-
258
- #### swagger
139
+ All settings are `optional`
259
140
 
260
- |option|children option|grandchild option|description|default|
261
- |------|---------------|-----------------|-----------|-------|
262
- |swagger|ui|image|Swagger UI Docker Image|`"swaggerapi/swagger-ui"`|
263
- |swagger|ui|port|Swagger UI Port|`"8080"`|
264
- |swagger|ui|exposed_port|Swagger UI Exposed Port|`"8080/tcp"`|
265
- |swagger|ui|volume|Swagger UI Volume|`"/app/swagger.json"`|
266
- |swagger|editor|image|Swagger Editor Docker Image|`"swaggerapi/swagger-editor"`|
267
- |swagger|editor|port|Swagger Editor Port|`"8080"`|
268
- |swagger|editor|exposed_port|Swagger Editor Exposed Port|`"8080/tcp"`|
269
-
270
- #### hook
271
-
272
- |option|description|default|
273
- |------|-----------|-------|
274
- |use_object_classes|Object class(hook class) to generate Openapi document|{ info_object: `R2OAS::Schema::V3::InfoObject`,<br>paths_object: `R2OAS::Schema::V3::PathsObject`,<br>path_item_object: `R2OAS::Schema::V3::PathItemObject`, external_document_object: `R2OAS::Schema::V3::ExternalDocumentObject`,<br> components_object: `R2OAS::Schema::V3::ComponentsObject`,<br> components_schema_object: `R2OAS::Schema::V3::Components::SchemaObject`, <br> components_request_body_object:`R2OAS::Schema::V3::Components::RequestBodyObject` }|
275
-
276
- #### tool
277
-
278
- |option|children option|grandchild option|description|default|
279
- |------|---------------|-----------------|-----------|-------|
280
- |tool|paths_stats|month_to_turn_to_warning_color|Elapsed month to issue a warning|`3`|
281
- |tool|paths_stats|warning_color|Warning Color|`:red`|
282
- |tool|paths_stats|table_title_color|Table Title Color|`:yellow`|
283
- |tool|paths_stats|heading_color|Heading Color|`:yellow`|
284
- |tool|paths_stats|highlight_color|Highlight Color|`:magenta`|
285
-
286
- Please refer to [here](https://github.com/janlelis/paint) for the color.
287
-
288
- ## Environment variables
289
-
290
- We explain the environment variables that can be set.
291
-
292
- |variable|description|default|
293
- |--------|-----------|-------|
294
- |PATHS_FILE|Specify one paths file path|`""`|
295
- |OAS_FILE|Specify swagger file path to analyze|`""`|
296
-
297
-
298
- ## .paths
299
-
300
- Writing file paths in .paths will only read them.
301
- You can comment out with `#`
302
-
303
- `oas_docs/.paths`
304
-
305
- ```
306
- #account_user_role.yml # ignore
307
- account.yml
308
- account.yml # ignore
309
- account.yml # ignore
310
- ```
141
+ Full docs are available at https://yukihirop.github.io/r2-oas/#/setting/configure
311
142
 
312
143
  ## 💊 Life Cycle Methods (Hook Metohds)
313
144
 
314
145
  Supported hook(life cycle methods) is like this:
315
146
 
316
- - `before_create`
317
- - `after_create`
318
-
319
- Supported Hook class is like this:
320
-
321
- - `R2OAS::Schema::V3::InfoObject`
322
- - `R2OAS::Schema::V3::PathsObject`
323
- - `R2OAS::Schema::V3::PathItemObject`
324
- - `R2OAS::Schema::V3::ExternalDocumentObject`
325
- - `R2OAS::Schema::V3::ComponentsObject`
326
- - `R2OAS::Schema::V3::Components::SchemaObject`
327
- - `R2OAS::Schema::V3::Components::RequestBodyObject`
328
-
329
- By inheriting these classes, you can hook them at the time of document generation by writing like this:
330
-
331
- #### case: InfoObject
332
-
333
- ```ruby
334
- class CustomInfoObject < R2OAS::Schema::V3::InfoObject
335
- before_create do |doc|
336
- # [Important] Please change doc destructively.
337
- # [Important] To be able to use methods in Rails !
338
- doc.merge!({
339
- # Something ....
340
- })
341
- end
342
-
343
- after_create do |doc, path|
344
- # [Important] Please change doc destructively.
345
- # [Important] To be able to use methods in Rails !
346
- doc.merge!({
347
- # Something ....
348
- })
349
- end
350
- end
351
- ```
352
-
353
- #### case: PathsObject
354
-
355
- ```ruby
356
- class CustomPathsObject < R2OAS::Schema::V3::PathsObject
357
- before_create do |doc|
358
- # [Important] Please change doc destructively.
359
- # [Important] To be able to use methods in Rails !
360
- doc.merge!({
361
- # Something ....
362
- })
363
- end
364
-
365
- after_create do |doc|
366
- # [Important] Please change doc destructively.
367
- # [Important] To be able to use methods in Rails !
368
- doc.merge!({
369
- # Something ....
370
- })
371
- end
372
- end
373
- ```
374
-
375
- #### case: PathItemObject
376
-
377
- ```ruby
378
- class CustomPathItemObject < R2OAS::Schema::V3::PathItemObject
379
- before_create do |doc, path|
380
- # [Important] Please change doc destructively.
381
- # [Important] To be able to use methods in Rails !
382
- doc.merge!({
383
- # Something ....
384
- })
385
- end
386
-
387
- after_create do |doc, schema_name|
388
- # [Important] Please change doc destructively.
389
- # [Important] To be able to use methods in Rails !
390
- doc.merge!({
391
- # Something ....
392
- })
393
- end
394
- end
395
- ```
396
-
397
- #### case: ExternalDocumentObject
398
-
399
- ```ruby
400
- class CustomExternalDocumentObject < R2OAS::Schema::V3::ExternalDocumentObject
401
- before_create do |doc|
402
- # [Important] Please change doc destructively.
403
- # [Important] To be able to use methods in Rails !
404
- doc.merge!({
405
- # Something ....
406
- })
407
- end
408
-
409
- after_create do |doc|
410
- # [Important] Please change doc destructively.
411
- # [Important] To be able to use methods in Rails !
412
- doc.merge!({
413
- # Something ....
414
- })
415
- end
416
- end
417
- ```
418
-
419
- #### case: ComponentsObject
420
-
421
- ```ruby
422
- class CustomComponentsObject < R2OAS::Schema::V3::ComponentsObject
423
- before_create do |doc|
424
- # [Important] Please change doc destructively.
425
- # [Important] To be able to use methods in Rails !
426
- doc.merge!({
427
- # Something ....
428
- })
429
- end
430
-
431
- after_create do |doc|
432
- # [Important] Please change doc destructively.
433
- # [Important] To be able to use methods in Rails !
434
- doc.merge!({
435
- # Something ....
436
- })
437
- end
438
- end
439
- ```
440
-
441
- #### case: Components::SchemaObject
442
-
443
- ```ruby
444
- class CustomComponentsSchemaObject < R2OAS::Schema::V3::Components::SchemaObject
445
- before_create do |doc, schema_name|
446
- # [Important] Please change doc destructively.
447
- # [Important] To be able to use methods in Rails !
448
- doc.merge!({
449
- # Something ....
450
- })
451
- end
452
-
453
- after_create do |doc, schema_name|
454
- # [Important] Please change doc destructively.
455
- # [Important] To be able to use methods in Rails !
456
- doc.merge!({
457
- # Something ....
458
- })
459
- end
460
- end
461
- ```
462
-
463
- If you want to determine the component schema name at runtime, like this:
464
-
465
- ```ruby
466
- class CustomComponentsSchemaObject < R2OAS::Schema::V3::Components::SchemaObject
467
- def components_schema_name(doc, path_component, tag_name, verb, http_status, schema_name)
468
- # [Important] Please return string.
469
- # default
470
- schema_name
471
- end
472
- end
473
- ```
474
-
475
- `path_component` is `R2OAS::Routing::PathComponent` instance.
476
-
477
- ```ruby
478
- module R2OAS
479
- module Routing
480
- class PathComponent < BaseComponent
481
- def initialize(path)
482
- def to_s
483
- def symbol_to_brace
484
- def path_parameters_data
485
- def path_excluded_path_parameters
486
- def exist_path_parameters?
487
- def path_parameters
488
- private
489
- def without_format
490
- ```
491
-
492
- #### case: Components::RequestBodyObject
493
-
494
- ```ruby
495
- class CustomComponentsRequestBodyObject < R2OAS::Schema::V3::Components::RequestBodyObject
496
- before_create do |doc, schema_name|
497
- # [Important] Please change doc destructively.
498
- # [Important] To be able to use methods in Rails !
499
- doc.merge!({
500
- # Something ....
501
- })
502
- end
503
-
504
- after_create do |doc, schema_name|
505
- # [Important] Please change doc destructively.
506
- # [Important] To be able to use methods in Rails !
507
- doc.merge!({
508
- # Something ....
509
- })
510
- end
511
- end
512
- ```
513
-
514
- If you want to determine the component schema name at runtime, like this:
515
-
516
- ```ruby
517
- class CustomComponentsRequestBodyObject < R2OAS::Schema::V3::Components::RequestBodyObject
518
- def components_request_body_name(doc, path_component, tag_name, verb, schema_name)
519
- # [Important] Please return string.
520
- # default
521
- schema_name
522
- end
523
-
524
- def components_schema_name(doc, path_component, tag_name, verb, schema_name)
525
- # [Important] Please return string.
526
- # default
527
- schema_name
528
- end
529
- end
530
- ```
531
-
532
- And write this to the configuration.
533
-
534
- ```ruby
535
- # If only InfoObject and PathItemObject, use a custom class
536
- R2OAS.configure do |config|
537
- #
538
- # omission ...
539
- #
540
- config.use_object_classes.merge!({
541
- info_object: CustomInfoObject,
542
- path_item_object: CustomPathItemObject
543
- })
544
- end
545
- ```
546
-
547
- This is the end.
147
+ Full docs are available at https://yukihirop.github.io/r2-oas/#/usage/use_hook_methods
548
148
 
549
149
  ## 🔩 CORS
550
150