zero-rails_openapi 1.5.2 → 1.5.3

data/README.md

@@ -5,8 +5,9 @@
   [![Maintainability](https://api.codeclimate.com/v1/badges/471fd60f6eb7b019ceed/maintainability)](https://codeclimate.com/github/zhandao/zero-rails_openapi/maintainability)
   [![Test Coverage](https://api.codeclimate.com/v1/badges/471fd60f6eb7b019ceed/test_coverage)](https://codeclimate.com/github/zhandao/zero-rails_openapi/test_coverage)
   [![Gitter Chat](https://badges.gitter.im/zero-rails_openapi/Lobby.svg)](https://gitter.im/zero-rails_openapi/Lobby)
-  
-  Concise DSL for generating OpenAPI Specification 3 (**OAS3**, formerly Swagger3) JSON documentation for Rails application, 
+  [![Help Contribute to Open Source](https://www.codetriage.com/zhandao/zero-rails_openapi/badges/users.svg)](https://www.codetriage.com/zhandao/zero-rails_openapi)
+
+  Concise DSL for generating OpenAPI Specification 3 (**OAS3**, formerly Swagger3) JSON documentation for Rails application,
   then you can use Swagger UI 3.2.0+ to show the documentation.
 
 ## Contributing
@@ -14,7 +15,7 @@
   **Hi, here is ZhanDao = ▽ =  
   I think it's a very useful tool when you want to write API document clearly.  
   I'm looking forward to your issue and PR, thanks!**
-  
+
   And, if you have any questions, please read the test code first.  
   such as [api DSL](spec/api_info_obj_spec.rb) and [schema Obj](spec/oas_objs/schema_obj_spec.rb).
 
@@ -24,6 +25,7 @@
 - [Installation](#installation)
 - [Configure](#configure)
 - [Usage - DSL](#usage---dsl)
+  - [Basic DSL](#basic-dsl)
   - [DSL methods inside `api` and `api_dry`'s block](#dsl-methods-inside-api-and-api_drys-block)
   - [DSL methods inside `components`'s block](#dsl-methods-inside-componentss-block-code-source)
 - [Run! - Generate JSON documentation file](#run---generate-json-documentation-file)
@@ -41,51 +43,51 @@
 ## About OAS
 
   Everything about OAS3 is on [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md)
-  
+
   You can getting started from [swagger.io](https://swagger.io/docs/specification/basic-structure/)
-  
+
   **I suggest you should understand OAS3's basic structure at least.**
-  such as component (can help you reuse DSL code, when your apis are used with the 
+  such as component (can help you reuse DSL code, when your apis are used with the
   same data structure).
 
 ## Installation
 
   Add this line to your Rails's Gemfile:
-  
+
   ```ruby
   gem 'zero-rails_openapi'
   # or
   gem 'zero-rails_openapi', github: 'zhandao/zero-rails_openapi'
   ```
-  
+
   And then execute:
-  
+
       $ bundle
-  
+
   Or install it yourself as:
-  
+
       $ gem install zero-rails_openapi
-    
+
 ## Configure
 
   Create an initializer, configure ZRO and define your OpenApi documents.
-  
+
   This is the simplest example:
-  
+
   ```ruby
   # config/initializers/open_api.rb
   require 'open_api'
-  
+
   OpenApi::Config.tap do |c|
     # [REQUIRED] The output location where .json doc file will be written to.
     c.file_output_path = 'public/open_api'
-  
+
     c.open_api_docs = {
         # The definition of the document `homepage`.
         homepage: {
             # [REQUIRED] ZRO will scan all the descendants of base_doc_class, then generate their docs.
             base_doc_class: Api::V1::BaseController,
-  
+
             # [REQUIRED] OAS Info Object: The section contains API information.
             info: {
                 # [REQUIRED] The title of the application.
@@ -102,14 +104,14 @@
     }
   end
   ```
-  
+
   In addition to directly using Hash,
   you can also use DSL to define the document information:
-  
+
   ```ruby
   # config/initializers/open_api.rb
   require 'open_api'
-  
+
   OpenApi::Config.tap do |c|
     c.instance_eval do
       open_api :homepage_api, base_doc_class: ApiDoc
@@ -117,7 +119,7 @@
     end
   end
   ```
-  
+
   For more detailed configuration: [open_api.rb](documentation/examples/open_api.rb)  
   See all the settings you can configure: [config.rb](lib/open_api/config.rb)  
   See all the Document Definition DSL: [config_dsl.rb](lib/open_api/config_dsl.rb)
@@ -136,7 +138,7 @@
 ### DSL Usage Example
 
   Here is the simplest usage:
-  
+
   ```ruby
   class Api::ExamplesController < ApiController
     api :index, 'GET list' do
@@ -145,11 +147,11 @@
     end
   end
   ```
-  
+
   For more example, see [goods_doc.rb](documentation/examples/goods_doc.rb), and
   [examples_controller.rb](documentation/examples/examples_controller.rb)
 
-### DSL as class methods ([source code](lib/open_api/dsl.rb))
+### Basic DSL ([source code](lib/open_api/dsl.rb))
 
 #### (1) `route_base` [optional if you're writing DSL in controller]
 
@@ -160,9 +162,9 @@
   route_base 'api/v1/examples'
   ```
   It is optional because `route_base` defaults to `controller_path`.
-  
-  [Here's a trick](#trick1---write-the-dsl-somewhere-else): Using `route_base`, you can write the DSL somewhere else 
-  to simplify the current controller.  
+
+  [Here's a trick](#trick1---write-the-dsl-somewhere-else): Using `route_base`, you can write the DSL somewhere else
+  to simplify the current controller.
 
 #### (2) `doc_tag` [optional]
 
@@ -170,11 +172,11 @@
   # method signature
   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. 
+  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)).
+
+  Tag's name defaults to controller_name. desc and external_doc_url are optional.
 
 #### (3) `components` [optional]
 
@@ -188,7 +190,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
@@ -196,15 +198,16 @@
     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 can be used to simplify your DSL code
+  (that is, to refer to the defined Component object by `*_ref` methods).
+
+  Each RefObj is associated with components through component key.
+  We suggest that component keys should be camelized, and must be Symbol.
 
 #### (4) `api_dry` [optional]
 
   This method is for DRYing.
-  
+
   ```ruby
   # method signature
   api_dry(action = :all, desc = '', &block)
@@ -215,37 +218,34 @@
     query! #...
   end
   ```
-  
+
   As you think, the block will be executed to each specified API(action) **firstly**.
-  
+
 #### (5) `api` [required]
 
-  Define the specified API (controller action, in the following example is index).
-  
+  Define the specified API
+  (or we could say controller action).
+
   ```ruby
   # method signature
-  api(action, summary = '', skip: [ ], use: [ ], &block)
+  api(action, summary = '', http: nil, skip: [ ], use: [ ], &block)
   # usage
   api :index, '(SUMMARY) this api blah blah ...', # block ...
   ```
-  
+
   `use` and `skip` options: to use or skip the parameters defined in `api_dry`.
-  
-  [Note] JBuilder file automatic generator has been removed,
-  If you need this function, please refer to [here](https://github.com/zhandao/zero-rails/tree/master/lib/generators/jubilder/dsl.rb) 
-  to implement a lib.
-  
+
   ```ruby
-  api :show, 'summary', use: [:id] # => it will only take :id from DRYed result.
+  api :show, 'summary', use: [:id] # it will only take :id from DRYed result to define the API :show
   ```
 
 ### DSL methods inside [api]() and [api_dry]()'s block
 
   [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:
@@ -261,7 +261,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)
@@ -275,9 +275,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))
@@ -285,7 +285,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
@@ -301,22 +301,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
@@ -324,7 +324,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
@@ -347,8 +347,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)
@@ -356,11 +356,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)
@@ -370,7 +370,7 @@
   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
@@ -398,36 +398,36 @@
   body!(media_type, data: { }, **options)
   # usage
   body :json
-  
-  
+
+
   # method implement
   def form data:, **options
     body :form, data: data, **options
   end
   # usage
   form! data: {
-          name: String,
-          password: String,
-          password_confirmation: String
-      }
+      name: String,
+      password: String,
+      password_confirmation: String
+  }
   # advance usage
   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'
-  
-  
+          :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_hash = { }
-    schema_hash[:type] = type if type.present?
-    form data: { name => schema_hash }
+  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
 
@@ -436,9 +436,9 @@
     body! media_type, data: data, **options
   end
   ```
-  
-  1. `media_type`: we provide some [mapping](lib/oas_objs/media_type_obj.rb) from symbols to real media-types.  
-  2. `schema_hash`: as above (see param).  
+
+  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: {
@@ -459,23 +459,23 @@
      data :param_a!, String
      data :param_b,  Integer
      # or same as:
-     form '', data: { :param_a! => String }
-     form '', data: { :param_b  => Integer }
+     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" ] } 
+     #   "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      # aliases: `resp` and `error`
   response_ref
   ```
-  
+
   ```ruby
   # method signature
   response(code, desc, media_type = nil, data: { }, type: nil)
@@ -490,17 +490,17 @@
   # usage
   response_ref 700 => :AResp, 800 => :BResp
   ```
-  
-  **practice:** Automatically generate responses based on the agreed error class. [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`
@@ -514,7 +514,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 = { })
@@ -524,16 +524,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
@@ -552,21 +552,21 @@
   ```
 
 #### (7) Overriding Global Servers by `server`
-  
+
   ```ruby
   # method signature
   server(url, desc: '')
   # usage
   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),
@@ -575,7 +575,7 @@
   ```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:
 
@@ -587,7 +587,7 @@
 
   ```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
@@ -611,22 +611,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
@@ -636,39 +636,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`).
 
 ### 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
@@ -677,19 +677,19 @@
   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!: {
@@ -708,27 +708,27 @@
   ```ruby
   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: {
+
+  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)
 
@@ -737,7 +737,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
@@ -745,7 +745,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.
 
@@ -753,10 +753,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.
@@ -764,7 +764,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