r2-oas 0.1.0 → 0.3.1

data/docs/usage/use_hook_methods.md

@@ -0,0 +1,236 @@
+# Use hook methods
+
+Supported hook(life cycle methods) is like this:
+
+- `before_create`
+- `after_create`
+
+Supported Hook class is like this:
+
+- `R2OAS::Schema::V3::InfoObject`
+- `R2OAS::Schema::V3::PathsObject`
+- `R2OAS::Schema::V3::PathItemObject`
+- `R2OAS::Schema::V3::ExternalDocumentObject`
+- `R2OAS::Schema::V3::ComponentsObject`
+- `R2OAS::Schema::V3::Components::SchemaObject`
+- `R2OAS::Schema::V3::Components::RequestBodyObject`
+
+By inheriting these classes, you can hook them at the time of document generation by writing like this:
+
+#### case: InfoObject
+
+```ruby
+class CustomInfoObject < R2OAS::Schema::V3::InfoObject
+  before_create do |doc|
+    # [Important] Please change doc destructively.
+    # [Important] To be able to use methods in Rails !
+    doc.merge!({
+      # Something .... 
+    })
+  end
+
+  after_create do |doc, path|
+    # [Important] Please change doc destructively.
+    # [Important] To be able to use methods in Rails !
+    doc.merge!({
+      # Something ....
+    })
+  end
+end
+```
+
+#### case: PathsObject
+
+```ruby
+class CustomPathsObject < R2OAS::Schema::V3::PathsObject
+  before_create do |doc|
+    # [Important] Please change doc destructively.
+    # [Important] To be able to use methods in Rails !
+    doc.merge!({
+      # Something .... 
+    })
+  end
+
+  after_create do |doc|
+    # [Important] Please change doc destructively.
+    # [Important] To be able to use methods in Rails !
+    doc.merge!({
+      # Something ....
+    })
+  end
+end
+```
+
+#### case: PathItemObject
+
+```ruby
+class CustomPathItemObject < R2OAS::Schema::V3::PathItemObject
+  before_create do |doc, path|
+    # [Important] Please change doc destructively.
+    # [Important] To be able to use methods in Rails !
+    doc.merge!({
+      # Something .... 
+    })
+  end
+
+  after_create do |doc, schema_name|
+    # [Important] Please change doc destructively.
+    # [Important] To be able to use methods in Rails !
+    doc.merge!({
+      # Something ....
+    })
+  end
+end
+```
+
+#### case: ExternalDocumentObject
+
+```ruby
+class CustomExternalDocumentObject < R2OAS::Schema::V3::ExternalDocumentObject
+  before_create do |doc|
+    # [Important] Please change doc destructively.
+    # [Important] To be able to use methods in Rails !
+    doc.merge!({
+      # Something .... 
+    })
+  end
+
+  after_create do |doc|
+    # [Important] Please change doc destructively.
+    # [Important] To be able to use methods in Rails !
+    doc.merge!({
+      # Something ....
+    })
+  end
+end
+```
+
+#### case: ComponentsObject
+
+```ruby
+class CustomComponentsObject < R2OAS::Schema::V3::ComponentsObject
+  before_create do |doc|
+    # [Important] Please change doc destructively.
+    # [Important] To be able to use methods in Rails !
+    doc.merge!({
+      # Something .... 
+    })
+  end
+
+  after_create do |doc|
+    # [Important] Please change doc destructively.
+    # [Important] To be able to use methods in Rails !
+    doc.merge!({
+      # Something ....
+    })
+  end
+end
+```
+
+#### case: Components::SchemaObject
+
+```ruby
+class CustomComponentsSchemaObject < R2OAS::Schema::V3::Components::SchemaObject
+  before_create do |doc, schema_name|
+    # [Important] Please change doc destructively.
+    # [Important] To be able to use methods in Rails !
+    doc.merge!({
+      # Something .... 
+    })
+  end
+
+  after_create do |doc, schema_name|
+    # [Important] Please change doc destructively.
+    # [Important] To be able to use methods in Rails !
+    doc.merge!({
+      # Something ....
+    })
+  end
+end
+```
+
+If you want to determine the component schema name at runtime, like this:
+
+```ruby
+class CustomComponentsSchemaObject < R2OAS::Schema::V3::Components::SchemaObject
+  def components_schema_name(doc, path_component, tag_name, verb, http_status, schema_name)
+    # [Important] Please return string.
+    # default
+    schema_name
+  end
+end
+```
+
+`path_component` is `R2OAS::Routing::PathComponent` instance.
+
+```ruby
+module R2OAS
+  module Routing
+    class PathComponent < BaseComponent
+      def initialize(path)
+      def to_s
+      def symbol_to_brace
+      def path_parameters_data
+      def path_excluded_path_parameters
+      def exist_path_parameters?
+      def path_parameters
+      private
+      def without_format
+```
+
+#### case: Components::RequestBodyObject
+
+```ruby
+class CustomComponentsRequestBodyObject < R2OAS::Schema::V3::Components::RequestBodyObject
+  before_create do |doc, schema_name|
+    # [Important] Please change doc destructively.
+    # [Important] To be able to use methods in Rails !
+    doc.merge!({
+      # Something .... 
+    })
+  end
+
+  after_create do |doc, schema_name|
+    # [Important] Please change doc destructively.
+    # [Important] To be able to use methods in Rails !
+    doc.merge!({
+      # Something ....
+    })
+  end
+end
+```
+
+If you want to determine the component schema name at runtime, like this:
+
+```ruby
+class CustomComponentsRequestBodyObject < R2OAS::Schema::V3::Components::RequestBodyObject
+  def components_request_body_name(doc, path_component, tag_name, verb, schema_name)
+    # [Important] Please return string.
+    # default
+    schema_name
+  end
+
+  def components_schema_name(doc, path_component, tag_name, verb, schema_name)
+    # [Important] Please return string.
+    # default
+    schema_name
+  end
+end
+```
+
+And write this to the configuration.
+
+```ruby
+# If only InfoObject and PathItemObject, use a custom class
+R2OAS.configure do |config|
+  # 
+  # omission ...
+  # 
+  config.use_object_classes.merge!({
+    info_object:      CustomInfoObject,
+    path_item_object: CustomPathItemObject
+  })
+end
+```
+
+This is the end.

data/docs/{HOW_TO_USE_HOOK_WHEN_GENERATE_DOC.md → usage/use_hook_to_generate_docs.md}

@@ -1,6 +1,8 @@
-## BasicUsage
+## Use hook to generate docs
 
-`custom_path_item_object.rb`
+## Prepare
+
+prepare a file like `custom_path_item_object.rb`
 
 ```ruby
 class CustomPathItemObject < R2OAS::Schema::V3::PathItemObject
@@ -56,25 +58,14 @@ end
 require_relative 'custom_path_item_object'
 
 R2OAS.configure do |config|
-  config.root_dir_path        = "./oas_docs"
-  config.schema_save_dir_name = "src"
-  config.doc_save_file_name   = "oas_doc.yml"
-  config.force_update_schema  = false
-  config.use_tag_namespace    = true
-  config.use_schema_namespace = false
-  config.server.data = [
-    {
-      url: "http://localhost:3000",
-      description: "localhost"
-    }
-  ]
-  config.interval_to_save_edited_tmp_schema = 15
   config.use_object_classes.merge!({
     path_item_object:  CustomPathItemObject
   })
 end
 ```
 
+## Command
+
 ```bash
 $ bundle exec rake routes:oas:docs
 ```
@@ -146,54 +137,54 @@ show_in_app GET         /:model_name/:id/show_in_app(.:format) rails_admin/main#
 ```
 $ bundle exec rake routes:oas:docs
 I, [2019-06-02T22:12:41.530676 #61323]  INFO -- : [R2-OAS] start
-I, [2019-06-02T22:12:41.609492 #61323]  INFO -- : [Generate Swagger schema files] start
+I, [2019-06-02T22:12:41.609492 #61323]  INFO -- : [Generate OAS schema files] start
 I, [2019-06-02T22:12:41.609574 #61323]  INFO -- : <From routes data>
 I, [2019-06-02T22:12:41.609591 #61323]  INFO -- : <Update schema files>
-I, [2019-06-02T22:12:41.611183 #61323]  INFO -- :  Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/openapi.yml
-I, [2019-06-02T22:12:41.611676 #61323]  INFO -- :  Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/info.yml
-I, [2019-06-02T22:12:41.612596 #61323]  INFO -- :  Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/tags.yml
-I, [2019-06-02T22:12:41.612619 #61323]  INFO -- :  [Generate Swagger schema files (paths)] start
+I, [2019-06-02T22:12:41.611183 #61323]  INFO -- :  Write schema file: 	oas_docs/src/openapi.yml
+I, [2019-06-02T22:12:41.611676 #61323]  INFO -- :  Write schema file: 	oas_docs/src/info.yml
+I, [2019-06-02T22:12:41.612596 #61323]  INFO -- :  Write schema file: 	oas_docs/src/tags.yml
+I, [2019-06-02T22:12:41.612619 #61323]  INFO -- :  [Generate OAS schema files (paths)] start
 I, [2019-06-02T22:12:41.612765 #61323]  INFO -- :  <From routes data>
 I, [2019-06-02T22:12:41.612782 #61323]  INFO -- :  <Update schema files (paths)>
-I, [2019-06-02T22:12:41.614701 #61323]  INFO -- :   Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/rails_admin/engine.yml
-I, [2019-06-02T22:12:41.618979 #61323]  INFO -- :   Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/api/v2/post.yml
-I, [2019-06-02T22:12:41.623081 #61323]  INFO -- :   Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/api/v1/post.yml
-I, [2019-06-02T22:12:41.630184 #61323]  INFO -- :   Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/api/v1/task.yml
-I, [2019-06-02T22:12:41.633369 #61323]  INFO -- :   Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/task.yml
-I, [2019-06-02T22:12:41.636323 #61323]  INFO -- :   Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/user.yml
-I, [2019-06-02T22:12:41.642353 #61323]  INFO -- :   Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/rails_admin/main.yml
-I, [2019-06-02T22:12:41.642381 #61323]  INFO -- :  [Generate Swagger schema files (paths)] end
-I, [2019-06-02T22:12:41.642664 #61323]  INFO -- :  Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/externalDocs.yml
-I, [2019-06-02T22:12:41.642993 #61323]  INFO -- :  Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/servers.yml
-I, [2019-06-02T22:12:41.643015 #61323]  INFO -- :  [Generate Swagger schema files (components)] start
+I, [2019-06-02T22:12:41.614701 #61323]  INFO -- :   Write schema file: 	oas_docs/src/paths/rails_admin/engine.yml
+I, [2019-06-02T22:12:41.618979 #61323]  INFO -- :   Write schema file: 	oas_docs/src/paths/api/v2/post.yml
+I, [2019-06-02T22:12:41.623081 #61323]  INFO -- :   Write schema file: 	oas_docs/src/paths/api/v1/post.yml
+I, [2019-06-02T22:12:41.630184 #61323]  INFO -- :   Write schema file: 	oas_docs/src/paths/api/v1/task.yml
+I, [2019-06-02T22:12:41.633369 #61323]  INFO -- :   Write schema file: 	oas_docs/src/paths/task.yml
+I, [2019-06-02T22:12:41.636323 #61323]  INFO -- :   Write schema file: 	oas_docs/src/paths/user.yml
+I, [2019-06-02T22:12:41.642353 #61323]  INFO -- :   Write schema file: 	oas_docs/src/paths/rails_admin/main.yml
+I, [2019-06-02T22:12:41.642381 #61323]  INFO -- :  [Generate OAS schema files (paths)] end
+I, [2019-06-02T22:12:41.642664 #61323]  INFO -- :  Write schema file: 	oas_docs/src/externalDocs.yml
+I, [2019-06-02T22:12:41.642993 #61323]  INFO -- :  Write schema file: 	oas_docs/src/servers.yml
+I, [2019-06-02T22:12:41.643015 #61323]  INFO -- :  [Generate OAS schema files (components)] start
 I, [2019-06-02T22:12:41.643335 #61323]  INFO -- :  <From routes data>
 I, [2019-06-02T22:12:41.643421 #61323]  INFO -- :  <Update Components schema files (components/schemas)>
-I, [2019-06-02T22:12:41.645158 #61323]  INFO -- :   Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/components/schemas/engine.yml
-I, [2019-06-02T22:12:41.645613 #61323]  INFO -- :   Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/components/schemas/post.yml
-I, [2019-06-02T22:12:41.645987 #61323]  INFO -- :   Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/components/schemas/task.yml
-I, [2019-06-02T22:12:41.646443 #61323]  INFO -- :   Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/components/schemas/user.yml
-I, [2019-06-02T22:12:41.646833 #61323]  INFO -- :   Write schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/components/schemas/main.yml
-I, [2019-06-02T22:12:41.646853 #61323]  INFO -- :  [Generate Swagger schema files (components)] end
-I, [2019-06-02T22:12:41.646865 #61323]  INFO -- : [Generate Swagger schema files] end
-I, [2019-06-02T22:12:41.646874 #61323]  INFO -- : [Generate Swagger docs from schema files] start
-I, [2019-06-02T22:12:41.647400 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/openapi.yml
-I, [2019-06-02T22:12:41.648404 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/user.yml
-I, [2019-06-02T22:12:41.649983 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/api/v1/task.yml
-I, [2019-06-02T22:12:41.651386 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/api/v1/post.yml
-I, [2019-06-02T22:12:41.652608 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/api/v2/post.yml
-I, [2019-06-02T22:12:41.654068 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/task.yml
-I, [2019-06-02T22:12:41.654754 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/rails_admin/engine.yml
-I, [2019-06-02T22:12:41.658028 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/paths/rails_admin/main.yml
-I, [2019-06-02T22:12:41.658622 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/externalDocs.yml
-I, [2019-06-02T22:12:41.659216 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/tags.yml
-I, [2019-06-02T22:12:41.659715 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/components/schemas/user.yml
-I, [2019-06-02T22:12:41.660165 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/components/schemas/task.yml
-I, [2019-06-02T22:12:41.660528 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/components/schemas/engine.yml
-I, [2019-06-02T22:12:41.660788 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/components/schemas/main.yml
-I, [2019-06-02T22:12:41.661004 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/components/schemas/post.yml
-I, [2019-06-02T22:12:41.661261 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/info.yml
-I, [2019-06-02T22:12:41.661520 #61323]  INFO -- :  Use schema file: 	/Users/yukihirop/RubyProjects/r2-oas/oas_docs/src/servers.yml
-I, [2019-06-02T22:12:41.686435 #61323]  INFO -- : [Generate Swagger docs from schema files] end
+I, [2019-06-02T22:12:41.645158 #61323]  INFO -- :   Write schema file: 	oas_docs/src/components/schemas/engine.yml
+I, [2019-06-02T22:12:41.645613 #61323]  INFO -- :   Write schema file: 	oas_docs/src/components/schemas/post.yml
+I, [2019-06-02T22:12:41.645987 #61323]  INFO -- :   Write schema file: 	oas_docs/src/components/schemas/task.yml
+I, [2019-06-02T22:12:41.646443 #61323]  INFO -- :   Write schema file: 	oas_docs/src/components/schemas/user.yml
+I, [2019-06-02T22:12:41.646833 #61323]  INFO -- :   Write schema file: 	oas_docs/src/components/schemas/main.yml
+I, [2019-06-02T22:12:41.646853 #61323]  INFO -- :  [Generate OAS schema files (components)] end
+I, [2019-06-02T22:12:41.646865 #61323]  INFO -- : [Generate OAS schema files] end
+I, [2019-06-02T22:12:41.646874 #61323]  INFO -- : [Generate OAS docs from schema files] start
+I, [2019-06-02T22:12:41.647400 #61323]  INFO -- :  Use schema file: 	oas_docs/src/openapi.yml
+I, [2019-06-02T22:12:41.648404 #61323]  INFO -- :  Use schema file: 	oas_docs/src/paths/user.yml
+I, [2019-06-02T22:12:41.649983 #61323]  INFO -- :  Use schema file: 	oas_docs/src/paths/api/v1/task.yml
+I, [2019-06-02T22:12:41.651386 #61323]  INFO -- :  Use schema file: 	oas_docs/src/paths/api/v1/post.yml
+I, [2019-06-02T22:12:41.652608 #61323]  INFO -- :  Use schema file: 	oas_docs/src/paths/api/v2/post.yml
+I, [2019-06-02T22:12:41.654068 #61323]  INFO -- :  Use schema file: 	oas_docs/src/paths/task.yml
+I, [2019-06-02T22:12:41.654754 #61323]  INFO -- :  Use schema file: 	oas_docs/src/paths/rails_admin/engine.yml
+I, [2019-06-02T22:12:41.658028 #61323]  INFO -- :  Use schema file: 	oas_docs/src/paths/rails_admin/main.yml
+I, [2019-06-02T22:12:41.658622 #61323]  INFO -- :  Use schema file: 	oas_docs/src/externalDocs.yml
+I, [2019-06-02T22:12:41.659216 #61323]  INFO -- :  Use schema file: 	oas_docs/src/tags.yml
+I, [2019-06-02T22:12:41.659715 #61323]  INFO -- :  Use schema file: 	oas_docs/src/components/schemas/user.yml
+I, [2019-06-02T22:12:41.660165 #61323]  INFO -- :  Use schema file: 	oas_docs/src/components/schemas/task.yml
+I, [2019-06-02T22:12:41.660528 #61323]  INFO -- :  Use schema file: 	oas_docs/src/components/schemas/engine.yml
+I, [2019-06-02T22:12:41.660788 #61323]  INFO -- :  Use schema file: 	oas_docs/src/components/schemas/main.yml
+I, [2019-06-02T22:12:41.661004 #61323]  INFO -- :  Use schema file: 	oas_docs/src/components/schemas/post.yml
+I, [2019-06-02T22:12:41.661261 #61323]  INFO -- :  Use schema file: 	oas_docs/src/info.yml
+I, [2019-06-02T22:12:41.661520 #61323]  INFO -- :  Use schema file: 	oas_docs/src/servers.yml
+I, [2019-06-02T22:12:41.686435 #61323]  INFO -- : [Generate OAS docs from schema files] end
 I, [2019-06-02T22:12:41.686477 #61323]  INFO -- : [R2-OAS] end
 ```
 

data/docs/{HOW_TO_USE_SCHEMA_NAMESPACE.md → usage/use_schema_namespace.md}

@@ -1,20 +1,27 @@
-## Use Schema Namespace (default)
+# Use Schema Namespace
+
+## Prepare
+
+Add this line to your application's Gemfile:
 
 ```ruby
+group :development do
+  gem 'r2-oas'
+end
+```
+
+Add the following settings to your rails project's `config/environments/development.rb`.
 
+```ruby
 require 'r2-oas'
 
 R2OAS.configure do |config|
-   # default setting        
-   config.root_dir_path        = "./oas_docs"
-   config.schema_save_dir_name = "src"
-   config.doc_save_file_name   = "oas_doc.yml"
-   # default
-   config.use_tag_namespace    = true
-   config.use_schema_namespace = true # write here
- end
+  config.use_schema_namespace = true
+end
 ```
 
+## Command
+
 ```bash
 $ bundle exec rake routes:oas:docs
 ```
@@ -88,37 +95,36 @@ Generate like this:
 ```
 oas_docs
 ├── schema
-│   ├── components
-│   │   └── schemas
-│   │       ├── api
-│   │       │   ├── v1
-│   │       │   │   ├── post.yml
-│   │       │   │   └── task.yml
-│   │       │   └── v2
-│   │       │       └── post.yml
-│   │       ├── rails_admin
-│   │       │   ├── engine.yml
-│   │       │   └── main.yml
-│   │       ├── task.yml
-│   │       └── user.yml
-│   ├── externalDocs.yml
-│   ├── info.yml
-│   ├── openapi.yml
-│   ├── paths
-│   │   ├── api
-│   │   │   ├── v1
-│   │   │   │   ├── post.yml
-│   │   │   │   └── task.yml
-│   │   │   └── v2
-│   │   │       └── post.yml
-│   │   ├── rails_admin
-│   │   │   ├── engine.yml
-│   │   │   └── main.yml
-│   │   ├── task.yml
-│   │   └── user.yml
-│   ├── servers.yml
-│   └── tags.yml
-└── oas_doc.yml
+    ├── components
+    │   └── schemas
+    │       ├── api
+    │       │   ├── v1
+    │       │   │   ├── post.yml
+    │       │   │   └── task.yml
+    │       │   └── v2
+    │       │       └── post.yml
+    │       ├── rails_admin
+    │       │   ├── engine.yml
+    │       │   └── main.yml
+    │       ├── task.yml
+    │       └── user.yml
+    ├── externalDocs.yml
+    ├── info.yml
+    ├── openapi.yml
+    ├── paths
+    │   ├── api
+    │   │   ├── v1
+    │   │   │   ├── post.yml
+    │   │   │   └── task.yml
+    │   │   └── v2
+    │   │       └── post.yml
+    │   ├── rails_admin
+    │   │   ├── engine.yml
+    │   │   └── main.yml
+    │   ├── task.yml
+    │   └── user.yml
+    ├── servers.yml
+    └── tags.yml
 ```
 
 ## Do not Use Tag Namespace
@@ -172,5 +178,4 @@ oas_docs
 │   │   └── user.yml
 │   ├── servers.yml
 │   └── tags.yml
-└── oas_doc.yml
 ```