zero-rails_openapi 1.5.2 → 1.5.3

data/README_zh.md

@@ -27,6 +27,7 @@
 - [安装](#installation)
 - [配置](#configure)
 - [DSL 介绍及用例](#usage---dsl)
+  - [基本的 DSL](#基本的-dsl)
   - [用于 `api` 和 `api_dry` 块内的 DSL（描述 API 的参数、响应等）](#dsl-methods-inside-api-and-api_drys-block)
   - [用于 `components` 块内的 DSL（描述可复用的组件）](#dsl-methods-inside-componentss-block-code-source)
 - [执行文档生成](#run---generate-json-documentation-file)
@@ -47,8 +48,7 @@
   
   你也可以看这份文档做初步的了解 [swagger.io](https://swagger.io/docs/specification/basic-structure/)
   
-  **我建议你应该至少了解 OAS3 的基本结构**
-  比如说 component（组件）—— 这能帮助你进一步减少书写文档 DSL 的代码（如果其中有很多可复用的数据结构的话）。
+  **建议你应该至少了解 OAS3 的基本结构**，比如说 component（组件）—— 这能帮助你进一步减少书写文档 DSL 的代码（如果其中有很多可复用的数据结构的话）。
 
 ## Installation
 
@@ -132,7 +132,7 @@
 
 ### DSL 使用实例
 
-  这是一个最简单的实例：
+  一个最简单的实例：
   
   ```ruby
   class Api::ExamplesController < ApiController
@@ -143,10 +143,10 @@
   end
   ```
   
-  可以查看两份更详细的实例： [goods_doc.rb](documentation/examples/goods_doc.rb), 以及
-  [examples_controller.rb](documentation/examples/examples_controller.rb)
+  这有两份更详细的实例： [goods_doc.rb](documentation/examples/goods_doc.rb), 以及
+  [examples_controller.rb](documentation/examples/examples_controller.rb)。
 
-### 作为类方法的 DSL ([source code](lib/open_api/dsl.rb))
+### 基本的 DSL ([source code](lib/open_api/dsl.rb))
 
 #### (1) `route_base` [无需调用，当且仅当你是在控制器中写文档时]
 
@@ -156,7 +156,7 @@
   # usage
   route_base 'api/v1/examples'
   ```
-  其默认设定为 `controller_path`.
+  其默认设定为 `controller_path`。
   
   [这个技巧](#trick1---write-the-dsl-somewhere-else) 展示如何使用 `route_base` 来让你将 DSL 写在他处（与控制器分离），来简化你的控制器。
 
@@ -164,13 +164,14 @@
 
   ```ruby
   # method signature
-  doc_tag(name: nil, desc: '', external_doc_url: '')
+  doc_tag(name: nil, desc: '', external_doc_url: nil)
   # usage
-  doc_tag name: 'ExampleTagName', desc: 'ExamplesController\'s APIs'
+  doc_tag name: 'ExampleTagName', desc: "ExamplesController's APIs"
   ```
-  This method allows you to set the Tag (which is a node of [OpenApi Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#openapi-object)).  
-  
-  desc and external_doc_url will be output to the tags[the current tag] (tag defaults to controller_name), but are optional. 
+  该方法可以设置当前类中声明的 API 的 Tag
+  (Tag 是一个 [OpenApi Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#openapi-object)节点)。
+
+  Tag 的名字默认为 controller_name，除了名字，还可以设置可选参数 desc 和 external_doc_url。
 
 #### (3) `components` [optional]
 
@@ -184,7 +185,7 @@
     query! :UidQuery  => [ :uid, String, desc: 'uid' ]
     resp   :BadRqResp => [ 'bad request', :json ]
   end
-  
+
   # to use component
   api :action, 'summary' do
     query :doge, :DogSchema # to use a Schema component
@@ -192,15 +193,15 @@
     response_ref :BadRqResp # to use a Response component
   end
   ```
-  Component can be used to simplify your DSL code (by using `*_ref` methods).
-  
-  Each RefObj you defined is associated with components through component key.
-  We suggest that component keys should be camelized symbol.
+  Component 用以简化你的 DSL 代码 (即通过 `*_ref` 形式的方法，来引用已定义的 Component 对象)。
+
+  每个 RefObj 都是通过 component key 来关联指定的 component。
+  我们建议 component key 规范为驼峰命名法，且必须是 Symbol。
 
 #### (4) `api_dry` [optional]
 
-  This method is for DRYing.
-  
+  顾名思义，此方法用于 DRY。
+
   ```ruby
   # method signature
   api_dry(action = :all, desc = '', &block)
@@ -211,36 +212,33 @@
     query! #...
   end
   ```
-  
-  As you think, the block will be executed to each specified API(action) **firstly**.
-  
+
+  如你所觉，传给该方法的块，将会 eval 到指定的 API 的**开头**。
+
 #### (5) `api` [required]
 
-  Define the specified API (controller action, in the following example is index).
-  
+  定义指定 API (或者说是一个 controller action).
+
   ```ruby
   # method signature
-  api(action, summary = '', builder: nil, skip: [ ], use: [ ], &block)
+  api(action, summary = '', http: nil, skip: [ ], use: [ ], &block)
   # usage
-  api :index, '(SUMMARY) this api blah blah ...', builder: :index # block ...
+  api :index, '(SUMMARY) this api blah blah ...', # block ...
   ```
-  If you pass `builder`, and `generate_jbuilder_file` is set to `true` (in your initializer),
-  ZRO will generate JBuilder file by using specified template called `index`.  
-  About template settings, see: [open_api.rb](documentation/examples/open_api.rb)
-  
-  `use` and `skip` options: to use or skip the parameters defined in `api_dry`.
-  
+
+  `use` 和 `skip`: 指定使用或者跳过在 `api_dry` 中声明的参数。
+
   ```ruby
-  api :show, 'summary', use: [:id] # => it will only take :id from DRYed result.
+  api :show, 'summary', use: [:id] # 将会从 dry 块中声明的参数中挑出 id 这个参数用于 API :show
   ```
 
-### DSL methods inside [api]() and [api_dry]()'s block
+### 用于 [`api`]() 和 [`api_dry`]() 块内的 DSL
 
   [source code](lib/open_api/dsl/api_info_obj.rb)
-  
+
   These following methods in the block describe the specified API action: description, valid?,
   parameters, request body, responses, securities, servers.
-  
+
   (Here corresponds to OAS [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#operationObject))
 
 #### (1) `this_api_is_invalid!`, its aliases:
@@ -256,7 +254,7 @@
   # usage
   this_api_is_invalid! 'this api is expired!'
   ```
-  
+
   Then `deprecated` of this API will be set to true.
 
 #### (2) `desc`: description for the current API and its inputs (parameters and request body)
@@ -270,9 +268,9 @@
        email: 'desc of the parameter :email'
   ```
 
-  You can of course describe the input in it's DSL method (like `query! :done ...`, [this line](https://github.com/zhandao/zero-rails_openapi#-dsl-usage-example)), 
+  You can of course describe the input in it's DSL method (like `query! :done ...`, [this line](https://github.com/zhandao/zero-rails_openapi#dsl-usage-example)),
   but that will make it long and ugly. We recommend that unite descriptions in this place.
-  
+
   In addition, when you want to dry the same parameters (each with a different description), it will be of great use.
 
 #### (3) `param` family methods (OAS - [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#parameterObject))
@@ -280,7 +278,7 @@
   Define the parameters for the API (action).
   ```
   param
-  param_ref                          # for reuse component, 
+  param_ref                          # for reuse component,
                                      #   it links sepcified RefObjs (by component keys) to current parameters.
   header,  path,  query,  cookie     # will pass specified parameter location to `param`
   header!, path!, query!, cookie!    # bang method of above methods
@@ -296,22 +294,22 @@
   # `schema_type` is the type of parameter, like: String, Integer (must be a constant)
   # For more explanation, please click the link below ↓↓↓
   # method signature
-  param(param_type, param_name, schema_type, is_required, schema_hash = { })
+  param(param_type, param_name, schema_type, is_required, schema_info = { })
   # usage
   param :query, :page, Integer, :req,  range: { gt: 0, le: 5 }, desc: 'page'
-  
-  
+
+
   # method signature
   param_ref(component_key, *component_keys) # should pass at least 1 key
   # usage
   param_ref :IdPath
   param_ref :IdPath, :NameQuery, :TokenHeader
-  
-  
+
+
   ### method signature
-   header(param_name, schema_type = nil, one_of: nil, all_of: nil, any_of: nil, not: nil, **schema_hash)
-  header!(param_name, schema_type = nil, one_of: nil, all_of: nil, any_of: nil, not: nil, **schema_hash)
-   query!(param_name, schema_type = nil, one_of: nil, all_of: nil, any_of: nil, not: nil, **schema_hash)
+   header(param_name, schema_type = nil, **schema_info)
+  header!(param_name, schema_type = nil, **schema_info)
+   query!(param_name, schema_type = nil, **schema_info)
   # ...
   ### usage
   header! 'Token', String
@@ -319,7 +317,7 @@
   # The same effect as above, but not simple
   param :query, :readed, Boolean, :req, must_be: true, default: false
   #
-  # When schema_type is a Object 
+  # When schema_type is a Object
   #   (describe by hash, key means prop's name, value means prop's schema_type)
   query :good, { name: String, price: Float, spec: { size: String, weight: Integer } }, desc: 'good info'
   # Or you can use `type:` to sign the schema_type, maybe this is clearer for describing object
@@ -342,8 +340,8 @@
   query  :search_type, String
   query  :search_val, String
   query! :export, Boolean
-  
-  
+
+
   # method signature
   # `exp_by` (select_example_by): choose the example fields.
   examples(exp_by = :all, examples_hash)
@@ -351,11 +349,11 @@
   # it defines 2 examples by using parameter :id and :name
   # if pass :all to `exp_by`, keys will be all the parameter's names.
   examples [:id, :name], {
-          :right_input => [ 1, 'user'], # == { id: 1, name: 'user' }
-          :wrong_input => [ -1, ''   ]
+      :right_input => [ 1, 'user'], # == { id: 1, name: 'user' }
+      :wrong_input => [ -1, ''   ]
   }
   ```
-  
+
   [This trick show you how to define combined schema (by using `one_of` ..)](#trick6---combined-schema-one-of--all-of--any-of--not)
 
   [**>> More About `param` DSL <<**](documentation/parameter.md)
@@ -365,20 +363,22 @@
   OpenAPI 3.0 uses the requestBody keyword to distinguish the payload from parameters.
   ```
   request_body
-  body_ref      # for reuse component, 
+  body_ref      # for reuse component,
                 #   it links sepcified RefObjs (by component keys) to current body.
   body, body!   # alias of request_body
   form, form!   # define a multipart/form-data body
+  data          # define [a] property in the form-data body
   file, file!   # define a File media-type body
   ```
-  
+  Bang methods(!) means the specified media-type body is required.
+
   ```ruby
   # method signature
-  request_body(is_required, media_type, desc = '', schema_hash = { })
+  request_body(required, media_type, data: { }, **options)
   # usage
-  request_body :opt, :form, '', type: { id!: Integer, name: String }
-  # or
-  request_body :opt, :form, '', data: { id!: Integer, name: String }
+  # (1) `data` contains all the attributes required by this request body.
+  # (2) `param_name!` means it is required, otherwise without '!' means optional.
+  request_body :opt, :form, data: { id!: Integer, name: { type: String, desc: 'name' } }, desc: 'form-data'
 
 
   # method signature
@@ -388,96 +388,112 @@
 
 
   # method signature
-  body!(media_type, desc = '', schema_hash = { })
+  body!(media_type, data: { }, **options)
   # usage
   body :json
-  
-  
+
+
   # method implement
-  def form desc = '', schema_hash = { }
-    body :form, desc, schema_hash
+  def form data:, **options
+    body :form, data: data, **options
   end
   # usage
-  form! 'register', data: {
-          name: String,
-          password: String,
-          password_confirmation: String
-      }
+  form! data: {
+      name: String,
+      password: String,
+      password_confirmation: String
+  }
   # advance usage
-  form 'for creating a user', data: {
-              :name! => { type: String, desc: 'user name' },
-          :password! => { type: String, pattern: /[0-9]{6,10}/, desc: 'password' },
-          # optional
-            :remarks => { type: String, desc: 'remarks' },
-      }, exp_by:            %i[ name password ],
-         examples: {         #    ↓        ↓
-             :right_input => [ 'user1', '123456' ],
-             :wrong_input => [ 'user2', 'abc'    ]
-         }
+  form data: {
+          :name! => { type: String, desc: 'user name' },
+      :password! => { type: String, pattern: /[0-9]{6,10}/, desc: 'password' },
+      # optional
+        :remarks => { type: String, desc: 'remarks' },
+  }, exp_by:            %i[ name password ],
+     examples: {         #    ↓        ↓
+         :right_input => [ 'user1', '123456' ],
+         :wrong_input => [ 'user2', 'abc'    ]
+     },
+  desc: 'for creating a user'
+
 
+  # method implement
+  def data name, type = nil, schema_info = { }
+    schema_info[:type] = type if type.present?
+    form data: { name => schema_info }
+  end
+  # usage: please look at the 4th point below
 
   # about `file`
-  def file! media_type, desc = '', schema_hash = { type: File }
-    body! media_type, desc, schema_hash
+  def file! media_type, data: { type: File }, **options
+    body! media_type, data: data, **options
   end
   ```
-  
-  1. **Notice:** Each API should only declare a request body
-     That is, all of the above methods you can only choose one of them.  
-     (But **multiple media types** will be supported in the future).
-  2. `media_type`: we provide some [mapping](lib/oas_objs/media_type_obj.rb) from symbols to real media-types.  
-  3. `schema_hash`: as above (see param).  
-     **One thing that should be noted is: when use Hash writing, `scham_type` is writed in schema_hash using key :type.**
-  4. `exp_by` and `examples`: for the above example, the following has the same effect:
+
+  1. `media_type`: we provide some [mapping](lib/oas_objs/media_type_obj.rb) from symbols to real media-types.
+  2. `schema_info`: as above (see param).
+  3. `exp_by` and `examples`: for the above example, the following has the same effect:
      ```
      examples: {
          :right_input => { name: 'user1', password: '123456' },
          :wrong_input => { name: 'user2', password: 'abc' }
      }
      ```
-  
+  4. *[IMPORTANT]* Each request bodies you declared will **FUSION** together. <a name="fusion"></a>  
+     (1) Media-Types will be merged to `requestBody["content"]`
+     ```ruby
+     form data: { }, desc: 'desc'
+     body :json, data: { }, desc: 'desc'
+     # will generate: "content": { "multipart/form-data": { }, "application/json": { } }
+     ```
+     (2) The same media-types will fusion, but not merge:  
+         (So that you can write `form` separately, and make `data` method possible.)
+     ```ruby
+     data :param_a!, String
+     data :param_b,  Integer
+     # or same as:
+     form data: { :param_a! => String }
+     form data: { :param_b  => Integer }
+     # will generate: { "param_a": { "type": "string" }, "param_b": { "type": "integer" } } (call it X)
+     # therefore:
+     #   "content": { "multipart/form-data":
+     #     { "schema": { "type": "object", "properties": { X }, "required": [ "param_a" ] }
+     #   }
+     ```
+
 #### (5) `response` family methods (OAS - [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#response-object))
-  
+
   Define the responses for the API (action).
   ```
-  response or resp
+  response      # aliases: `resp` and `error`
   response_ref
-  default_response or dft_resp
-  error_response, other_response, oth_resp, error, err_resp # response's aliases, should be used in the error response context.
-  merge_to_resp
   ```
-  
+
   ```ruby
   # method signature
-  response(response_code, desc, media_type = nil, schema_hash = { })
+  response(code, desc, media_type = nil, data: { }, type: nil)
   # usage
+  resp 200, 'json response', :json, data: { name: 'test' }
   response 200, 'query result', :pdf, type: File
+  # same as:
+  response 200, 'query result', :pdf, data: File
 
   # method signature
   response_ref(code_compkey_hash)
   # usage
   response_ref 700 => :AResp, 800 => :BResp
-
-  # method signature
-  merge_to_resp(code, by:)
-  # usage
-  merge_to_resp 200, by: {
-      data: {
-          type: String
-      }
-  }
   ```
-  
-  **practice:** Combined with wrong class, automatically generate error responses. [AutoGenDoc](documentation/examples/auto_gen_doc.rb#L63)  
-  
+
+  **practice:** Automatically generate responses based on the agreed error class. [AutoGenDoc](documentation/examples/auto_gen_doc.rb#L63)
+
 #### (6) Authentication and Authorization
-  
-  First of all, please make sure that you have read one of the following documents:  
-  [OpenApi Auth](https://swagger.io/docs/specification/authentication/) 
+
+  First of all, please make sure that you have read one of the following documents:
+  [OpenApi Auth](https://swagger.io/docs/specification/authentication/)
   or [securitySchemeObject](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securitySchemeObject)
-  
+
   ##### Define Security Scheme
-  
+
   Use these DSL in your initializer or `components` block:
   ```
   security_scheme # alias `auth_scheme`
@@ -491,7 +507,7 @@
   security_scheme(scheme_name, other_info)
   # usage
   security_scheme :BasicAuth, { type: 'http', scheme: 'basic', desc: 'basic auth' }
-  
+
   # method signature
   base_auth(scheme_name, other_info = { })
   bearer_auth(scheme_name, format = 'JWT', other_info = { })
@@ -501,16 +517,16 @@
   bearer_auth :Token
   api_key :ApiKeyAuth, field: 'X-API-Key', in: 'header', desc: 'pass api key to header'
   ```
-  
+
   ##### Apply Security
-  
+
   ```
   # In initializer
   # Global effectiveness
   global_security_require
   global_security # alias
   global_auth     # alias
-  
+
   # In `api`'s block
   # Only valid for the current controller
   security_require
@@ -529,42 +545,42 @@
   ```
 
 #### (7) Overriding Global Servers by `server`
-  
+
   ```ruby
   # method signature
-  server(url, desc)
+  server(url, desc: '')
   # usage
-  server 'http://localhost:3000', 'local'
+  server 'http://localhost:3000', desc: 'local'
   ```
-  
+
 ### DSL methods inside [components]()'s block ([code source](lib/open_api/dsl/components.rb))
 
   (Here corresponds to OAS [Components Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#componentsObject))
-    
+
   Inside `components`'s block,
   you can use the same DSL as [[DSL methods inside `api` and `api_dry`'s block]](#dsl-methods-inside-api-and-api_drys-block).
-  But there are two differences:  
-  
+  But there are two differences:
+
   (1) Each method needs to pass one more parameter `component_key`
     (in the first parameter position),
     this will be used as the reference name for the component.
-  
+
   ```ruby
   query! :UidQuery, :uid, String
   ```
-  This writing is feasible but not recommended, 
+  This writing is feasible but not recommended,
   because component's key and parameter's name seem easy to confuse.
   The recommended writing is:
-  
+
   ```ruby
   query! :UidQuery => [:uid, String]
   ```
-  
+
   (2) You can use `schema` to define a Schema Component.
-  
+
   ```ruby
   # method signature
-  schema(component_key, type = nil, one_of: nil, all_of: nil, any_of: nil, not: nil, **schema_hash)
+  schema(component_key, type = nil, **schema_info)
   # usage
   schema :Dog  => [ String, desc: 'dogee' ] # <= schema_type is `String`
   # advance usage
@@ -588,22 +604,22 @@
 ## Run! - Generate JSON Documentation File
 
   Use `OpenApi.write_docs`:
-  
+
   ```ruby
   # initializer
   OpenApi.write_docs generate_files: !Rails.env.production?
-  
+
   # or run directly in console
   OpenApi.write_docs # will generate json doc files
   ```
-  
+
   Then the JSON files will be written to the directories you set. (Each API a file.)
 
 ## Use Swagger UI(very beautiful web page) to show your Documentation
 
-  Download [Swagger UI](https://github.com/swagger-api/swagger-ui) (version >= 2.3.0 support the OAS3) 
-  to your project,  
-  change the default JSON file path(url) in index.html.  
+  Download [Swagger UI](https://github.com/swagger-api/swagger-ui) (version >= 2.3.0 support the OAS3)
+  to your project,
+  change the default JSON file path(url) in index.html.
   In order to use it, you may have to enable CORS, [see](https://github.com/swagger-api/swagger-ui#cors-support)
 
 ## Tricks
@@ -613,39 +629,39 @@
   Does your documentation take too many lines?  
   Do you want to separate documentation from business controller to simplify both?  
   Very easy! Just follow
-  
+
   ```ruby
   # config/initializers/open_api.rb
   # in your configuration
   base_doc_class: ApiDoc
-  
+
   # app/api_doc/api_doc.rb
   require 'open_api/dsl'
-  
+
   class ApiDoc < Object
     include OpenApi::DSL
   end
-  
+
   # app/api_doc/v1/examples_doc.rb
   class V1::ExamplesDoc < ApiDoc
     route_base 'api/v1/examples'
-    
+
     api :index do
       # ...
     end
   end
   ```
-  
+
   Notes: file name ends in `_doc.rb` by default, but you can change via `Config.doc_location`
-    (it should be file paths, defaults to `./app/**/*_doc.rb`).
+  (it should be file paths, defaults to `./app/**/*_doc.rb`).
 
 ### Trick2 - Global DRYing
 
   Method `api_dry` is for DRY but its scope is limited to the current controller.
-  
+
   I have no idea of best practices, But you can look at this [file](documentation/examples/auto_gen_doc.rb).  
   The implementation of the file is: do `api_dry` when inherits the base controller inside `inherited` method.
-  
+
   You can use `sort` to specify the order of parameters.
 
 ### Trick3 - Auto Generate Description
@@ -654,22 +670,22 @@
   desc 'api desc',
        search_type!: 'search field, allows：<br/>'
   query :search_type, String, enum: %w[name creator category price]
-  
+
   # or
-  
+
   query :search_type, String, desc!: 'search field, allows：<br/>',
         enum: %w[name creator category price]
   ```
-  
+
   Notice `!` use (`search_type!`, `desc!`), it tells ZRO to append
   information that analyzed from definitions (enum, must_be ..) to description automatically.
-  
-  Any one of above will generate:  
+
+  Any one of above will generate:
   > search field, allows：<br/>1/ name<br/>2/ creator,<br/>3/ category<br/>4/ price<br/>
-  
+
   You can also use Hash to define `enum`:
   ```ruby
-  query :view, String, desc: 'allows values<br/>', enum: {
+  query :view, String, desc: 'allows values<br/>', enum!: {
           'all goods (default)': :all,
                   'only online': :online,
                  'only offline': :offline,
@@ -683,29 +699,29 @@
 
   Pass `skip: []` and `use: []` to `api` like following code:
   ```ruby
-  api :index, 'desc', builder: :index, skip: [ :Token ]
+  api :index, 'desc', skip: [ :Token ]
   ```
-  
+
   Look at this [file](documentation/examples/goods_doc.rb) to learn more.
 
 ### Trick5 - Auto Generate index/show Actions's Response-Types Based on DB Schema
 
   Use method `load_schema` in `api_dry`.
-  
+
   See this [file](documentation/examples/auto_gen_doc.rb#L51) for uasge information.
 
 ### Trick6 - Combined Schema (one_of / all_of / any_of / not)
 
   ```ruby
-  query :combination, one_of: [ :GoodSchema, String, { type: Integer, desc: 'integer input'}]
-  
-  form '', data: {
+  query :combination, one_of: [ :GoodSchema, String, { type: Integer, desc: 'integer input' } ]
+
+  form data: {
       :combination_in_form => { any_of: [ Integer, String ] }
   }
-  
+
   schema :PetSchema => [ not: [ Integer, Boolean ] ]
   ```
-  
+
   OAS: [link1](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/),
   [link2](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject)
 
@@ -714,7 +730,7 @@
 - **You wrote document of the current API, but not find in the generated json file?**  
   Check your routing settings.
 - **Undefine method `match?`**  
-  Monkey patches for `String` and `Symbol`:  
+  Monkey patches for `String` and `Symbol`:
   ```ruby
   class String # Symbol
     def match?(pattern); !match(pattern).nil? end
@@ -722,7 +738,7 @@
   ```
 - **Report error when require `routes.rb`?***
   1. Run `rails routes`.
-  2. Copy the output to a file, for example `config/routes.txt`.  
+  2. Copy the output to a file, for example `config/routes.txt`.
      Ignore the file `config/routes.txt`.
   3. Put `c.rails_routes_file = 'config/routes.txt'` to your ZRO config.
 
@@ -730,10 +746,10 @@
 ## About `OpenApi.docs` and `OpenApi.routes_index`
 
   After `OpenApi.write_docs`, the above two module variables will be generated.
-  
+
   `OpenApi.docs`: A Hash with API names as keys, and documents of each APIs as values.  
   documents are instances of ActiveSupport::HashWithIndifferentAccess.
-  
+
   `OpenApi.routes_index`: Inverted index of controller path to API name mappings.  
   Like: `{ 'api/v1/examples' => :homepage_api }`  
   It's useful when you want to look up a document based on a controller and do something.
@@ -741,7 +757,7 @@
 ## Development
 
   After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-  
+
   To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## License