r2-oas 0.1.0 → 0.1.2

data/README.md

@@ -4,7 +4,7 @@
 [![Coverage Status](https://coveralls.io/repos/github/yukihirop/r2-oas/badge.svg)](https://coveralls.io/github/yukihirop/r2-oas)
 [![Maintainability](https://api.codeclimate.com/v1/badges/f8c3846f350bb412fd63/maintainability)](https://codeclimate.com/github/yukihirop/r2-oas/maintainability)
 
-Generate api docment(OpenAPI) side only from `rails` routing.
+Generate api docment(OpenAPI) side only from `Rails` routing.
 
 Provides a rake command to help `generate` , `view` , and `edit` OpenAPI documents.
 
@@ -62,88 +62,7 @@ bundle exec routes:oas:docs
 bundle exec routes:oas:editor
 ```
 
-## 📖 Usage
-
-All settings are optional. The initial value is as follows.
-
-In your rails project, Write `config/environments/development.rb` like that:
-
-```ruby
-# default setting
-R2OAS.configure do |config|
-  config.version                            = :v3
-  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.interval_to_save_edited_tmp_schema = 15
-  # :dot or :underbar
-  config.namespace_type                     = :underbar
-  config.deploy_dir_path                    = "./deploy_docs"
-
-  config.server.data = [
-    {
-      url: "http://localhost:3000",
-      description: "localhost"
-    }
-  ]
-
-  config.swagger.configure do |swagger|
-    swagger.ui.image            = "swaggerapi/swagger-ui"
-    swagger.ui.port             = "8080"
-    swagger.ui.exposed_port     = "8080/tcp"
-    swagger.ui.volume           = "/app/swagger.json"
-    swagger.editor.image        = "swaggerapi/swagger-editor"
-    swagger.editor.port         = "81"
-    swagger.editor.exposed_port = "8080/tcp" 
-  end
-
-  config.use_object_classes = {
-    info_object:                    R2OAS::Schema::V3::InfoObject,
-    paths_object:                   R2OAS::Schema::V3::PathsObject,
-    path_item_object:               R2OAS::Schema::V3::PathItemObject,
-    external_document_object:       R2OAS::Schema::V3::ExternalDocumentObject,
-    components_object:              R2OAS::Schema::V3::ComponentsObject,
-    components_schema_object:       R2OAS::Schema::V3::Components::SchemaObject,
-    components_request_body_object: R2OAS::Schema::V3::Components::RequestBodyObject
-  }
-
-  config.http_statuses_when_http_method = {
-    get: {
-      default: %w(200 422),
-      path_parameter: %w(200 404 422)
-    },
-    post: {
-      default: %w(201 422),
-      path_parameter: %w(201 404 422)
-    },
-    patch: {
-      default: %w(204 422),
-      path_parameter: %w(204 404 422)
-    },
-    put: {
-      default: %w(204 422),
-      path_parameter: %w(204 404 422)
-    },
-    delete: {
-      default: %w(200 422),
-      path_parameter: %w(200 404 422)
-    }
-  }
-
-  config.http_methods_when_generate_request_body = %w[post patch put]
-
-  config.tool.paths_stats.configure do |paths_stats|
-    paths_stats.month_to_turn_to_warning_color = 3
-    paths_stats.warning_color                  = :red
-    paths_stats.table_title_color              = :yellow
-    paths_stats.heading_color                  = :yellow
-    paths_stats.highlight_color                = :magenta
-  end
-end
-```
+## Usage
 
 You can execute the following command in the root directory of rails.
 
@@ -179,20 +98,9 @@ $ bundle exec rake routes:oas:paths_ls
 $ bundle exec rake routes:oas:paths_stats
 ```
 
-## 📚 More Usage
-
-- [How to generate docs](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_GENERATE_DOCS.md)
-- [How to start swagger editor](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_START_SWAGGER_EDITOR.md)
-- [How to start swagger ui](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_START_SWAGGER_UI.md)
-- [How to monitor swagger document](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_MONITOR_SWAGGER_DOC.md)
-- [How to analyze docs](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_ANALYZE_DOCS.md)
-- [How to clean docs](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_CLEAN_DOCS.md)
-- [How to deploy swagger doc](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_DEPLOY_SWAGGER_DOC.md)
-- [How to use tag namespace](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_USE_TAG_NAMESPACE.md)
-- [How to use schema namespace](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_USE_SCHEMA_NAMESPACE.md)
-- [How to use hook when generate doc](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_USE_HOOK_WHEN_GENERATE_DOC.md)
-- [How to display paths list](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_DISPLAY_PATHS_LIST.md)
-- [How to display paths stats](https://github.com/yukihirop/r2-oas/blob/master/docs/HOW_TO_DISPLAY_PATHS_STATS.md)
+## 📚 Documents
+
+Full docs are available at https://yukihirop.github.io/r2-oas
 
 ## ❤️ Support Rails Version
 
@@ -209,9 +117,7 @@ $ bundle exec rake routes:oas:paths_stats
 
 ## ❤️ Support OpenAPI Schema
 
-|version|document|
-|-------|--------|
-|v3|[versions/v3.md](https://github.com/yukihirop/r2-oas/blob/master/docs/versions/v3.md)|
+Full docs are available at https://yukihirop.github.io/r2-oas/#/schema/3.0.0
 
 ## ❗️ Convention over Configuration (CoC)
 
@@ -230,321 +136,15 @@ $ bundle exec rake routes:oas:paths_stats
 
 ## ⚙ Configure
 
-we explain the options that can be set.
-
-#### basic
-
-|option|description|default|
-|------|-----------|---|
-|version|OpenAPI schema version| `:v3` |
-|root_dir_path|Root directory for storing products.| `"./oas_docs"` |
-|schema_save_dir_name|Directory name for storing swagger schemas|`"src"`|
-|doc_save_file_name|File name for storing swagger doc|`"oas_doc.yml"`|
-|force_update_schema|Force update schema from routes data|`false`|
-|use_tag_namespace|Use namespace for tag name|`true`|
-|use_schema_namespace|Use namespace for schema name|`true`|
-|interval_to_save_edited_tmp_schema|Interval(sec) to save edited tmp schema|`15`|
-|http_statuses_when_http_method|Determine the response to support for each HTTP method|omission...|
-|http_methods_when_generate_request_body|HTTP methods when generate requestBody|`[post put patch]`|
-|namespace_type|namespace for components(schemas/requestBodies) name| `underbar` |
-|deploy_dir_path|deploy directory.|`"./deploy_docs"`|
-
-#### server
-
-|option|children option|description|default|
-|------|---------------|-----------|-------|
-|server|data|Server data (url, description) |[{ url: `http://localhost:3000`, description: `localhost` }] |
-
-#### swagger
+All settings are `optional`
 
-|option|children option|grandchild option|description|default|
-|------|---------------|-----------------|-----------|-------|
-|swagger|ui|image|Swagger UI Docker Image|`"swaggerapi/swagger-ui"`|
-|swagger|ui|port|Swagger UI Port|`"8080"`|
-|swagger|ui|exposed_port|Swagger UI Exposed Port|`"8080/tcp"`|
-|swagger|ui|volume|Swagger UI Volume|`"/app/swagger.json"`|
-|swagger|editor|image|Swagger Editor Docker Image|`"swaggerapi/swagger-editor"`|
-|swagger|editor|port|Swagger Editor Port|`"8080"`|
-|swagger|editor|exposed_port|Swagger Editor Exposed Port|`"8080/tcp"`|
-
-#### hook
-
-|option|description|default|
-|------|-----------|-------|
-|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` }|
-
-#### tool
-
-|option|children option|grandchild option|description|default|
-|------|---------------|-----------------|-----------|-------|
-|tool|paths_stats|month_to_turn_to_warning_color|Elapsed month to issue a warning|`3`|
-|tool|paths_stats|warning_color|Warning Color|`:red`|
-|tool|paths_stats|table_title_color|Table Title Color|`:yellow`|
-|tool|paths_stats|heading_color|Heading Color|`:yellow`|
-|tool|paths_stats|highlight_color|Highlight Color|`:magenta`|
-
-Please refer to [here](https://github.com/janlelis/paint) for the color.
-
-## Environment variables
-
-We explain the environment variables that can be set.
-
-|variable|description|default|
-|--------|-----------|-------|
-|PATHS_FILE|Specify one paths file path|`""`|
-|OAS_FILE|Specify swagger file path to analyze|`""`|
-
-
-## .paths
-
-Writing file paths in .paths will only read them.
-You can comment out with `#`
-
-`oas_docs/.paths`
-
-```
-#account_user_role.yml    # ignore
-account.yml
-account.yml               # ignore
-account.yml               # ignore
-```
+Full docs are available at https://yukihirop.github.io/r2-oas/#/setting/configure
 
 ## 💊 Life Cycle Methods (Hook Metohds)
 
 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.
+Full docs are available at https://yukihirop.github.io/r2-oas/#/usage/use_hook_methods
 
 ## 🔩 CORS