zero-rails_openapi 1.3.2 → 1.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 996bf583a71a6c1b34daa068d9fad89761fd8074
-  data.tar.gz: 97858fcf27fdf3bf491e28d8fcba9b5061cebf7c
+  metadata.gz: 5b5be5f5f85b9f720f9fafaa70ba037879c336e0
+  data.tar.gz: fc93ab5059ff2ff594e080e51cb349a9a1ffd64c
 SHA512:
-  metadata.gz: a46294ecd676e965ac1c4b0c3f7e0944751feae640882872d06f7ff52547b1c5b4bc4b71311d5a6b75fa98c66f18c2eb4832c7d2fc70b05c846cdae3456ec170
-  data.tar.gz: 16d36540905bee8b7f242dfadab8cc6f5edeffb83f88b936fc4da8ee6d2941fe0c206030781c8ae8121eed9a6e459dc5a8387b691b19491716a995ca1b1788a8
+  metadata.gz: f0f37a9cb0e11cb4850819e6ed443c6f6b2386ec0f2b47878eb16b1a375e2c50fb8c6b0a2cea3446010eb3b07bc7d709f6aa74b0773d23e88962c3037222e734
+  data.tar.gz: 0db4a7fdc0f13cb55b654ff1362d39a67c399ab5f8ffa0e40eabad9c3f4776042a77c2ac189af281de0208d274d441276c10aeb7fc2b4e486753cc2f0780cae0

data/Gemfile

@@ -4,5 +4,3 @@ git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in zero-rails_openapi.gemspec
 gemspec
-
-gem 'activesupport'

data/Gemfile.lock

@@ -1,21 +1,98 @@
 PATH
   remote: .
   specs:
-    zero-rails_openapi (1.3.2)
+    zero-rails_openapi (1.3.3)
+      activesupport (>= 3)
+      rails (>= 3)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    actioncable (5.1.4)
+      actionpack (= 5.1.4)
+      nio4r (~> 2.0)
+      websocket-driver (~> 0.6.1)
+    actionmailer (5.1.4)
+      actionpack (= 5.1.4)
+      actionview (= 5.1.4)
+      activejob (= 5.1.4)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (5.1.4)
+      actionview (= 5.1.4)
+      activesupport (= 5.1.4)
+      rack (~> 2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.1.4)
+      activesupport (= 5.1.4)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.3)
+    activejob (5.1.4)
+      activesupport (= 5.1.4)
+      globalid (>= 0.3.6)
+    activemodel (5.1.4)
+      activesupport (= 5.1.4)
+    activerecord (5.1.4)
+      activemodel (= 5.1.4)
+      activesupport (= 5.1.4)
+      arel (~> 8.0)
     activesupport (5.1.4)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (~> 0.7)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
+    arel (8.0.0)
+    builder (3.2.3)
     concurrent-ruby (1.0.5)
+    crass (1.0.2)
     diff-lcs (1.3)
-    i18n (0.9.0)
+    erubi (1.7.0)
+    globalid (0.4.1)
+      activesupport (>= 4.2.0)
+    i18n (0.9.1)
       concurrent-ruby (~> 1.0)
+    loofah (2.1.1)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.0)
+      mini_mime (>= 0.1.1)
+    method_source (0.9.0)
+    mini_mime (0.1.4)
+    mini_portile2 (2.3.0)
     minitest (5.10.3)
+    nio4r (2.1.0)
+    nokogiri (1.8.1)
+      mini_portile2 (~> 2.3.0)
+    rack (2.0.3)
+    rack-test (0.7.0)
+      rack (>= 1.0, < 3)
+    rails (5.1.4)
+      actioncable (= 5.1.4)
+      actionmailer (= 5.1.4)
+      actionpack (= 5.1.4)
+      actionview (= 5.1.4)
+      activejob (= 5.1.4)
+      activemodel (= 5.1.4)
+      activerecord (= 5.1.4)
+      activesupport (= 5.1.4)
+      bundler (>= 1.3.0)
+      railties (= 5.1.4)
+      sprockets-rails (>= 2.0.0)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.0.3)
+      loofah (~> 2.0)
+    railties (5.1.4)
+      actionpack (= 5.1.4)
+      activesupport (= 5.1.4)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
     rake (10.5.0)
     rspec (3.6.0)
       rspec-core (~> 3.6.0)
@@ -30,15 +107,25 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.6.0)
     rspec-support (3.6.0)
+    sprockets (3.7.1)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.1)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    thor (0.20.0)
     thread_safe (0.3.6)
     tzinfo (1.2.4)
       thread_safe (~> 0.1)
+    websocket-driver (0.6.5)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  activesupport
   bundler (~> 1.16.a)
   rake (~> 10.0)
   rspec (~> 3.0)

data/README.md

@@ -1,30 +1,29 @@
-# ZRO: OpenApi 3 DocGenerator for Rails
+# ZRO: OpenApi 3 JSON-Doc Generator for Rails
 
-[![Gem Version](https://badge.fury.io/rb/zero-rails_openapi.svg)](https://badge.fury.io/rb/zero-rails_openapi)
-[![Build Status](https://travis-ci.org/zhandao/zero-rails_openapi.svg?branch=master)](https://travis-ci.org/zhandao/zero-rails_openapi)
-
-Provide concise DSL for generating the OpenAPI Specification 3 (**OAS3**, formerly Swagger3) documentation JSON file for Rails application, 
-then you can use Swagger UI 3.2.0+ to show the documentation.
+  [![Gem Version](https://badge.fury.io/rb/zero-rails_openapi.svg)](https://badge.fury.io/rb/zero-rails_openapi)
+  [![Build Status](https://travis-ci.org/zhandao/zero-rails_openapi.svg?branch=master)](https://travis-ci.org/zhandao/zero-rails_openapi)
+  
+  Provide concise DSL for generating the OpenAPI Specification 3 (**OAS3**, formerly Swagger3) documentation JSON file for Rails application, 
+  then you can use Swagger UI 3.2.0+ to show the documentation.
 
 ## Contributing
 
-**Hi, here is ZhanDao. This gem was completed when I learned Ruby less than three months, 
-I'm not sure if it has problem, but it may have a lot to improve.  
-I'm looking forward to your issues and PRs, thanks!**
-
-Currently, I think the most important TODO is the Unit Test (RSpec, I want is), 
-but I dont have enough time now = ▽ =
+  **Hi, here is ZhanDao. This gem was completed when I learned Ruby less than three months, 
+  I'm not sure if it has problem, but it may have a lot to improve.  
+  I'm looking forward to your issues and PRs, thanks!**
+  
+  Currently, I think the most important TODO is the Unit Test (RSpec, I want is), 
+  but I dont have enough time now = ▽ =
 
 ## Table of Contents
 
 - [About OAS](#about-oas) (OpenAPI Specification)
 - [Installation](#installation)
 - [Configure](#configure)
-- [Usage](#usage)
-  - [DSL for documenting your controller](#dsl-for-documenting-your-controller)
-  - [Generate JSON documentation file](#generate-json-documentation-file)
-  - [Use Swagger UI(very beautiful web page) to show your Documentation](#use-swagger-uivery-beautiful-web-page-to-show-your-documentation)
-  - [Tricks](#tricks)
+- [Usage - DSL](#usage---dsl)
+- [Usage - Generate JSON documentation file](#usage---generate-json-documentation-file)
+- [Usage - Use Swagger UI(very beautiful web page) to show your Documentation](#usage---use-swagger-uivery-beautiful-web-page-to-show-your-documentation)
+- [Tricks](#tricks)
     - [Write DSL somewhere else](#trick1---write-the-dsl-somewhere-else)
     - [Global DRYing](#trick2---global-drying)
     - [Auto generate description](#trick3---auto-generate-description)
@@ -34,310 +33,352 @@ but I dont have enough time now = ▽ =
 
 ## 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 
-same data structure).
+  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 
+  same data structure).
 
 ## Installation
 
-Add this line to your Rails's Gemfile:
-
-```ruby
-gem 'zero-rails_openapi'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install zero-rails_openapi
+  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 APIs.
-
-This is the simplest configuration 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.register_docs = {
-      homepage_api: {
-          # [REQUIRED] ZRO will scan all the descendants of root_controller, then generate their docs.
-          root_controller: Api::V1::BaseController,
-
-          # [REQUIRED] OAS Info Object: The section contains API information.
-          info: {
-              # [REQUIRED] The title of the application.
-              title: 'Rails APIs',
-              # Description of the application.
-              description: 'API documentation of Rails Application. <br/>' \
-                           'Optional multiline or single-line Markdown-formatted description ' \
-                           'in [CommonMark](http://spec.commonmark.org/) or `HTML`.',
-              # [REQUIRED] The version of the OpenAPI document
-              # (which is distinct from the OAS version or the API implementation version).
-              version: '1.0.0'
-          }
-      }
-  }
-end
-```
-You can also set the *global configuration(/component)* of OAS: 
-Server Object / Security Scheme Object / Security Requirement Object ...
-
-For more detailed configuration: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/open_api.rb)
-
-## Usage
-
-### DSL for documenting your controller
-
-#### \> First of all, extend DSL for your base controller, for example:
-
-```ruby
-# application_controller.rb
-class ApplicationController < ActionController::API
-  include OpenApi::DSL
- end
-```
-
-#### \> [DSL Usage Example](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/examples_controller.rb)
-
-(TODO: I consider that, here should be put in a the simplest case.)
-```ruby
-class Api::V1::ExamplesController < Api::V1::BaseController
-  apis_tag name: 'ExampleTagName', desc: 'ExamplesController\'s APIs'
+  Create an initializer, configure ZRO and define your APIs.
   
-  components do
-    schema :Dog           => [ String, must_be: 'doge' ]
-    query! :QueryCompUuid => [ :product_uuid, String, desc: 'product uuid' ]
-    path!  :PathCompId    => [ :id, Integer, desc: 'user id' ]
-    resp   :RespComp      => [ 'bad request', :json ]
-    body!  :RqBodyComp    => [ :form ]
+  This is the simplest configuration 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.register_docs = {
+        homepage_api: {
+            # [REQUIRED] ZRO will scan all the descendants of root_controller, then generate their docs.
+            root_controller: Api::V1::BaseController,
+  
+            # [REQUIRED] OAS Info Object: The section contains API information.
+            info: {
+                # [REQUIRED] The title of the application.
+                title: 'Homepage APIs',
+                # Description of the application.
+                description: 'API documentation of Rails Application. <br/>' \
+                             'Optional multiline or single-line Markdown-formatted description ' \
+                             'in [CommonMark](http://spec.commonmark.org/) or `HTML`.',
+                # [REQUIRED] The version of the OpenAPI document
+                # (which is distinct from the OAS version or the API implementation version).
+                version: '1.0.0'
+            }
+        }
+    }
   end
-
-  api_dry %i[index show], 'common response' do
-    response '567', 'query result export', :pdf, type: File
+  ```
+  The following global configuration and component of OAS are allow to be set in the initializer: 
+  Server Object / Security Scheme Object / Security Requirement Object ...
+  
+  In addition to direct use of Hash, you can also use Config DSL to configure:
+  
+  ```ruby
+  # config/initializers/open_api.rb
+  require 'open_api'
+  
+  OpenApi::Config.tap do |c|
+    c.instance_eval do
+      api :homepage_api, root_controller: ApiDoc
+      info version: '1.0.0', title: 'Homepage APIs'
+    end
   end
+  ```
+  
+  For more detailed configuration: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/open_api.rb)  
+  See all the settings you can configure: [config.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/config.rb)
 
-  open_api :index, '(SUMMARY) this api blah blah ...', :builder_template1 do
-    this_api_is_invalid! 'this api is expired!'
-    desc 'Optional multiline or single-line Markdown-formatted description',
-         id:         'user id',
-         email_addr: 'email_addr\'s desc'
-    email = 'git@github.com'
-
-    query! :id,         Integer, enum: 0..5,     length: [1, 2], pattern: /^[0-9]$/, range: {gt:0, le:5}
-    query! :done,       Boolean, must_be: false, default: true,  desc: 'must be false'
-    query  :email_addr, String,  lth: :ge_3,     default: email  # is_a: :email
-    # form! 'form', type: { id!: Integer, name: String }
-    file :pdf, 'desc: the media type is application/pdf'
-    
-    response :success, 'success response', :json, type: :Dog
-    
-    security :ApiKeyAuth
-  end
+## Usage - DSL
 
-  open_api :show do
-    param_ref    :PathCompId, :QueryCompUuid
-    response_ref '123' => :RespComp, '223' => :RespComp
+### First of all, include DSL to your base controller (which is for writing docs), for example:
+
+  ```ruby
+  # app/controllers/api/api_controller.rb
+  class ApiController < ActionController::API
+    include OpenApi::DSL
   end
-end
+  ```
 
-```
+### DSL Usage Example
 
-#### \> Explanation
+  Here is the simplest usage:
+  
+  ```ruby
+  class Api::V1::ExamplesController < Api::V1::BaseController
+    open_api :index, 'GET list' do
+      query :page, Integer#, desc: 'page, greater than 1', range: { ge: 1 }, dft: 1
+      query :rows, Integer#, desc: 'per page', range: { ge: 1 }, default: 10
+    end
+  end
+  ```
+  
+  For more example, see [goods_doc.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/goods_doc.rb), and
+  [examples_controller.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/examples_controller.rb)
 
-#### \>\> controller class methods ([source code](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl.rb))
+### DSL methods of controller ([source code](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl.rb))
 
-- `ctrl_path` (controller path) [Optional]
+#### (1) `ctrl_path` (controller path) [optional]
 
   ```ruby
   # method signature
-  ctrl_path path
+  ctrl_path(path)
   # usage
   ctrl_path 'api/v1/examples'
   ```
-  This option 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)).  
+  It is optional because `ctrl_path` defaults to `controller_path`.
+  
   [Here's a trick](#trick1---write-the-dsl-somewhere-else): Using `ctrl_path`, you can write the DSL somewhere else 
   to simplify the current controller.  
-  \* take the tag from `path.split('/').last`
 
-- `apis_tag` [Optional]
+#### (2) `apis_tag` [optional]
 
   ```ruby
   # method signature
-  apis_tag name: nil, desc: '', external_doc_url: ''
+  apis_tag(name: nil, desc: '', external_doc_url: '')
   # usage
   apis_tag name: 'ExampleTagName', desc: 'ExamplesController\'s APIs'
   ```
-  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)).  
+  
+  desc and external_doc_url will be output to the tags[the current tag] (tag defaults to controller_name), but are optional. 
 
-- `components` [Optional]
+#### (3) `components` [optional]
 
   ```ruby
   # method signature
-  components &block
+  components(&block)
   # usage
   components do
     # DSL for defining components
-    schema :Dog => [ String, dft: { id: 1, name: 'pet' } ]
+    schema :DogSchema => [ { id: Integer, name: String }, dft: { id: 1, name: 'pet' } ]
+    query! :UidQuery  => [ :uid, String, desc: 'uid' ]
+    resp   :BadRqResp => [ 'bad request', :json ]
+  end
+  
+  # to use component
+  open_api :action, 'summary' do
+    query :doge, :DogSchema # to use a Schema component
+    param_ref :UidQuery     # to use a Parameter component
+    response_ref :BadRqResp # to use a Response component
   end
   ```
-  Component can be used to simplify your DSL code in `*_ref` methods.  
-  Each RefObj you define is associated with components through component key.
+  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.
 
-- `api_dry` [Optional]
+#### (4) `api_dry` [optional]
 
-  this method is for DRYing.
+  This method is for DRYing.
   
   ```ruby
   # method signature
-  api_dry method = :all, desc = '', &block
+  api_dry(action = :all, desc = '', &block)
   # usage
-  api_dry :all, 'common response' do; end
-  api_dry :index do; end
-  api_dry [:index, :show] do; end
+  api_dry :all, 'common response' # block ...
+  api_dry :index # block ...
+  api_dry [:index, :show] do
+    query! #...
+  end
   ```
   
-  As you think, the DSL methods in the block will be executed to each API that you set by method.
+  As you think, the block will be executed to each specified API(action) **firstly**.
   
-- `open_api` [Required]
+#### (5) `open_api` [required]
 
-  Define the specified API (in the following example is index).
+  Define the specified API (controller action, in the following example is index).
   
   ```ruby
   # method signature
-  open_api method, summary = '', builder: nil, skip: [ ], use: [ ], &block
+  open_api(action, summary = '', builder: nil, skip: [ ], use: [ ], &block)
   # usage
-  open_api :index, '(SUMMARY) this api blah blah ...', builder: :template1 do end
+  open_api :index, '(SUMMARY) this api blah blah ...', builder: :index # 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](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/open_api.rb)
+  
+  `use` and `skip` options: to use or skip the parameters defined in `api_dry`.
+  
+  ```ruby
+  open_api :show, 'summary', use: [:id] # => it will only take :id from DRYed result.
   ```
-  If pass `builder` to the third parameter,
-  and `generate_jbuilder_file` is set `true` in your initializer file,
-  ZRO will generate JBuilder file by using specified template that you set
-  `template1` in your setting file.  
-  You can see: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/open_api.rb)
-
-
-#### \>\> DSL methods inside *open_api* and *api_dry*'s block ([source code](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl_inside_block.rb):: ApiInfoObj)
 
-These methods in the block describe the specified API(s): description, valid?,
-parameters, request body, responses, securities, servers.
+### DSL methods inside [open_api]() and [api_dry]()'s block
 
-(Here corresponds to OAS [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#operationObject))
+  [source code](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl_inside_block.rb), ApiInfoObj
+  
+  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))
 
-- `this_api_is_invalid!`, its aliases are:
-  - `this_api_is_expired!`
-  - `this_api_is_unused!`
-  - `this_api_is_under_repair!`
+#### (1) `this_api_is_invalid!`, its aliases:
+  ```
+  this_api_is_expired!
+  this_api_is_unused!
+  this_api_is_under_repair!
+  ```
 
   ```ruby
   # method signature
-  this_api_is_invalid! explain = ''
+  this_api_is_invalid!(explain = '')
   # usage
   this_api_is_invalid! 'this api is expired!'
   ```
+  
+  Then `deprecated` of this API will be set to true.
 
-- `desc`: description for current API and its inputs (parameters and request body)
+#### (2) `desc`: description for the current API and its inputs (parameters and request body)
 
   ```ruby
   # method signature
-  desc desc, param_descs = { }
+  desc(desc, param_descs = { })
   # usage
   desc 'current API\'s description',
-       id:         'user id',
-       email_addr: 'email_addr\'s desc'
+       id:    'desc of the parameter :id',
+       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.
 
-- param family methods (OAS - [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#parameterObject))
-  - `param`
-  - `param_ref`
-  - `header`, `path`, `query`, `cookie` and bang methods: `header!`, `path!`, `query!`, `cookie!`  
-  - `do_* by: { }`  
-  **The bang method(`!`) means it is required, so without `!` means it is optional. the same below.**
+#### (3) `param` family methods (OAS - [Parameter Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#parameterObject))
 
-  Define the parameters for the API(operation).
-  You can use the Reference Object to link to parameters that are defined at the components/parameters by method param_ref().
+  Define the parameters for the API (action).
+  ```
+  param
+  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
+  do_* by: { parameter_definations } # batch definition parameters, such as do_path, do_query
+  order                              # order parameters by names array you passed
+  examples                           # define examples of parameters
+  ```
+  **The bang method (which's name is end of a exclamation point `!`) means this param is required, so without `!` means optional.**  
+  **THE SAME BELOW.**
 
   ```ruby
+  # `param_type` just is the location of parameter, like: query, path
+  # `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, name, type, required, schema_hash = { }
+  param(param_type, param_name, schema_type, is_required, schema_hash = { })
   # usage
-  param :query, :page, Integer, :req,  range: { gt: 0, le: 5 }, desc: 'page',
-        examples: { :example => 5 }
+  param :query, :page, Integer, :req,  range: { gt: 0, le: 5 }, desc: 'page'
+  
   
   # method signature
-  param_ref component_key, *component_keys
+  param_ref(component_key, *component_keys) # should pass at least 1 key
   # usage
-  param_ref :PathCompId
-  param_ref :PathCompId, :QueryComp#, ...
+  param_ref :IdPath
+  param_ref :IdPath, :NameQuery, :TokenHeader
+  
   
   # method signature
-  header  name, type, schema_hash = { }
-  header! name, type, schema_hash = { }
-  query!  name, type, schema_hash = { }
+   header(param_name, schema_type, schema_hash = { })
+  header!(param_name, schema_type, schema_hash = { })
+   query!(param_name, schema_type, schema_hash = { })
   # usage
   header! 'Token', String
-  query!  :read,   Boolean, must_be: true, default: false
+  query!  :readed, Boolean, must_be: true, default: false
+  # The same effect as above, but not simple
+  param   :query, :readed, Boolean, :req, must_be: true, default: false
+
 
   # method signature
-  do_query by:
+  do_query(by:)
   # usage
   do_query by: {
-    :search_type => { type: String  },
-        :export! => { type: Boolean }
+    search_type: String,
+     search_val: String,
+        export!: Boolean
   }
-  # Same as below, but a little more succinctly
+  # The same effect as above, but a little bit repetitive
   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)
+  # usage
+  # 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, ''   ]
+  }
   ```
 
-  [**>> More About Param DSL <<**](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/parameter.md)
+  [**>> More About `param` DSL <<**](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/parameter.md)
 
-- request_body family methods (OAS - [Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#requestBodyObject))
-  - `request_body`
-  - `body_ref`
-  - `body` and bang `body!`
-  - `form`, `form!`; `file`, `file!`
-  
-  OpenAPI 3.0 uses the requestBody keyword to distinguish the payload from parameters.  
-  Define the request body for the API(operation).
-  You can use the Reference Object to link to request body that is defined at the components/requestBodies by method body_ref().
+#### (4) `request_body` family methods (OAS - [Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#requestBodyObject))
+
+  OpenAPI 3.0 uses the requestBody keyword to distinguish the payload from parameters.
+  ```
+  request_body
+  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
+  file, file!   # define a File media-type body
+  ```
   
   ```ruby
   # method signature
-  request_body required, media_type, desc = '', hash = { }
+  request_body(is_required, media_type, desc = '', schema_hash = { })
   # usage
-  request_body :opt, :form, type: { id!: Integer, name: String }
+  request_body :opt, :form, '', type: { id!: Integer, name: String }
+  # or
+  request_body :opt, :form, '', data: { id!: Integer, name: String }
+
 
   # method signature
-  body_ref component_key
+  body_ref(component_key)
   # usage
-  body_ref :Body
+  body_ref :UpdateDogeBody
+
 
   # method signature
-  body! media_type, desc = '', hash = { }
+  body!(media_type, desc = '', schema_hash = { })
   # usage
   body :json
   
+  
   # method implement
-  def form desc = '', hash = { }
-    body :form, desc, hash
+  def form desc = '', schema_hash = { }
+    body :form, desc, schema_hash
   end
   # usage
   form! 'register', data: {
@@ -347,197 +388,208 @@ parameters, request body, responses, securities, servers.
       }
   # advance usage
   form 'for creating a user', data: {
-          :name! =>     { type: String, desc: 'user name' },
+              :name! => { type: String, desc: 'user name' },
           :password! => { type: String, pattern: /[0-9]{6,10}/, desc: 'password' },
           # optional
-          :remarks =>   { type: String, desc: 'remarks' },
-      }
+            :remarks => { type: String, desc: 'remarks' },
+      }, exp_by:            %i[ name password ],
+         examples: {         #    ↓        ↓
+             :right_input => [ 'user1', '123456' ],
+             :wrong_input => [ 'user2', 'abc'    ]
+         }
 
-  # method implement
-  def file! media_type, desc = '', hash = { type: File }
-    body! media_type, desc, hash
+
+  # about `file`
+  def file! media_type, desc = '', schema_hash = { type: File }
+    body! media_type, desc, schema_hash
   end
   ```
   
-  (1) **Notice:** Each API can only declare a request body. 
-  That is, all of the above methods you can only choose one of them.  
-  (2) Media Type: We provide some [mapping](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/oas_objs/media_type_obj.rb) from symbols to real media-types.  
-  (3) schema_hash: As above (see param), it's just one more a `type` (schema type).
-  (4) `examples` usage see [goods_doc](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/goods_doc.rb)
+  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](https://github.com/zhandao/zero-rails_openapi/blob/master/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:
+     ```
+     examples: {
+         :right_input => { name: 'user1', password: '123456' },
+         :wrong_input => { name: 'user2', password: 'abc' }
+     }
+     ```
   
-- response family methods (OAS - [Response Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#response-object))
-  - `response` (`resp`)
-  - `response_ref`
-  - `default_response` (`dft_resp`)
-  - `error_response` (`other_response`, `oth_resp`, `error`, `err_resp`): Are `response`'s aliases, should be used in the error response context.
-  - `override_response` # TODO
+#### (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(operation).
-  You can use the Response Object to link to request body that is defined at the components/responses by method response_ref().
+  Define the responses for the API (action).
+  ```
+  response or resp
+  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.
+  ```
   
   ```ruby
   # method signature
-  response code, desc, media_type = nil, hash = { }
+  response(response_code, desc, media_type = nil, schema_hash = { })
   # usage
-  response 200, 'query result export', :pdf, type: File
+  response 200, 'query result', :pdf, type: File
 
   # method signature
-  response_ref code_compkey_hash
+  response_ref(code_compkey_hash)
   # usage
-  response_ref 700 => :RespComp, 800 => :RespComp
+  response_ref 700 => :AResp, 800 => :BResp
   ```
   
-  (1) **practice:** Combined with wrong class, automatically generate error responses. TODO  
-  (2) `examples` usage see [goods_doc](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/goods_doc.rb)
+  **practice:** Combined with wrong class, automatically generate error responses. [AutoGenDoc](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/auto_gen_doc.rb#L63)  
   
-- security: TODO
+#### (6) `security`: TODO
 
-- server: TODO
+#### (7) `server`: TODO
   
-#### \>\> DSL methods inside components'block ([code source](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl_inside_block.rb):: CtrlInfoObj )
+### DSL methods inside [components]()'block ([code source](https://github.com/zhandao/zero-rails_openapi/blob/master/lib/open_api/dsl_inside_block.rb):: CtrlInfoObj )
 
-(Here corresponds to OAS [Components Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#componentsObject))
-
-These methods in the block describe the current controller, 
-in other words, these methods eventually produce reusable components.
-
-So, the following methods are used as above, except that you need to 
-name the key of the component, and pass it as the first of argument list, like:
-
-```ruby
-query! :QueryCompUuid, :product_uuid, Integer, ...
-```
-This writing is feasible but not recommended, 
-because component's key and parameter's name looks like the same level.
-The recommended writing is:
+  (Here corresponds to OAS [Components Object](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#componentsObject))
+  
+  These methods in the block describe reusable components that you wanna use to define
+  parameter, response, request body and schema.
 
-```ruby
-query! :QueryCompUuid => [:product_uuid, Integer, ...]
-```
-The DSL methods used to generate the components in this block are: 
+  ```ruby
+  query! :UidQuery, :uid, String
+  ```
+  This writing is feasible but not recommended, 
+  because component's key and parameter's name looks like the same level.
+  The recommended writing is:
 
-- param family methods (except `param_ref`) (explained above)
-- request_body family methods (except `body_ref`) (explained above)
-- schema: define Schema Object component.
+  ```ruby
+  query! :UidQuery => [:uid, String]
+  ```
   
   ```ruby
   # method signature
-  schema component_key, type, schema_hash
+  schema(component_key, type, schema_hash)
   # usage
-  schema :Dog  => [ { id!: Integer, name: String }, dft: { id: 1, name: 'pet' } ]
+  schema :Dog  => [ String, desc: 'dogee' ]
   # advance usage
   schema :Dog => [{
                        id!: Integer,
-                       name: { type: String, must_be: 'zhandao', desc: 'name' }
-                   }, # this is schema type*
-                   dft: { id: 1, name: 'pet' }]
+                       name: { type: String, must_be: 'name', desc: 'name' }
+                   }, # <= this hash is schema type[1]
+                   dft: { id: 1, name: 'pet' },
+                   desc: 'dogee']
   # or (unrecommended)
-  schema :Dog, { id!: Integer, name: String }, dft: { id: 1, name: 'pet' }
+  schema :Dog, { id!: Integer, name: String }, dft: { id: 1, name: 'pet' }, desc: 'dogee'
   ```
-  *: see: [Type](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/parameter.md#type)
-
-### Generate JSON Documentation File
-
-Initializer or Console, run:
+  [1] see: [Type](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/parameter.md#type)
 
-```ruby
-OpenApi.write_docs
-```
+## Usage - Generate JSON Documentation File
 
-Then the JSON files will be written to the directory 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,  
-modify the default JSON file path(url) in the index.html 
-(window.onload >> SwaggerUIBundle >> url).  
-In order to use it, you may have to enable CORS, [see](https://github.com/swagger-api/swagger-ui#cors-support)
-
-### Tricks
-
-#### Trick1 - Write the DSL Somewhere Else
+  Use `OpenApi.write_docs`:
+  
+  ```ruby
+  # initializer
+  OpenApi.write_docs generate_files: !Rails.env.production?
+  
+  # or run directly in console
+  OpenApi.write_docs
+  ```
+  
+  Then the JSON files will be written to the directories you set. (Each API a file.)
 
-Does your documentation take too many lines?  
-Do you want to separate documentation from business controller to simplify both?  
-Very easy! Just use `ctrl_path`.
+## Usage - Use Swagger UI(very beautiful web page) to show your Documentation
 
-```ruby
-# config/initializers/open_api.rb
-# in your configure
-root_controller: BaseDoc
+  Download [Swagger UI](https://github.com/swagger-api/swagger-ui) (version >= 2.3.0 support the OAS3) 
+  to your project,  
+  modify the default JSON file path(url) in the index.html 
+  (window.onload >> SwaggerUIBundle >> url).  
+  In order to use it, you may have to enable CORS, [see](https://github.com/swagger-api/swagger-ui#cors-support)
 
-# app/api_doc/base_doc.rb
-require 'open_api/dsl'
+## Tricks
 
-class BaseDoc < Object
-  include OpenApi::DSL
-end
+### Trick1 - Write the DSL Somewhere Else
 
-# app/api_doc/v1/examples_doc.rb
-class V1::ExamplesDoc < BaseDoc
-  ctrl_path 'api/v1/examples'
+  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
+  root_controller: ApiDoc
   
-  open_api :index do
-    # ...
+  # app/api_doc/api_doc.rb
+  require 'open_api/dsl'
+  
+  class ApiDoc < Object
+    include OpenApi::DSL
   end
-end
-```
-
-Notes: convention is the file name ends with `_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](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/auto_gen_doc.rb).  
-The implementation of the file is: do `api_dry` when inherits the base controller inside `inherited` method.
-
-#### Trick3 - Auto Generate Description
-
-```ruby
-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.
+  
+  # app/api_doc/v1/examples_doc.rb
+  class V1::ExamplesDoc < ApiDoc
+    ctrl_path 'api/v1/examples'
+    
+    open_api :index do
+      # ...
+    end
+  end
+  ```
+  
+  Notes: convention is the file name ends with `_doc.rb`
 
-Any one of above will generate:  
-> search field, allows：<br/>1/ name<br/>2/ creator,<br/>3/ category<br/>4/ price<br/>
+### Trick2 - Global DRYing
 
-ZRO also allows you use Hash to define `enum`:
-```ruby
-query :view, String, enum: {
-        'all goods (default)': :all,
-        'only online':         :online,
-        'only offline':        :offline,
-        'expensive goods':     :get,
-        'cheap goods':         :borrow,
-    }
-```
-Read this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/auto_gen_desc.rb) to learn more.
+  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](https://github.com/zhandao/zero-rails_openapi/blob/master/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.
 
-#### Trick4 - Skip or Use parameters define in api_dry
+### Trick3 - Auto Generate Description
 
-Pass `skip: []` and `use: []` to `open_api` like following code:
-```ruby
-open_api :index, 'desc', builder: :index, skip: [ :Token ]
-```
+  ```ruby
+  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:  
+  > 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: {
+          'all goods (default)': :all,
+                  'only online': :online,
+                 'only offline': :offline,
+              'expensive goods': :get,
+                  'cheap goods': :borrow,
+      }
+  ```
+  Read this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/auto_gen_desc.rb) to learn more.
 
-Look at this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/goods_doc.rb) to learn more.
+### Trick4 - Skip or Use parameters define in api_dry
 
-#### Trick5 - Auto Generate index/show Actions's Response-Types Based on DB Schema
+  Pass `skip: []` and `use: []` to `open_api` like following code:
+  ```ruby
+  open_api :index, 'desc', builder: :index, skip: [ :Token ]
+  ```
+  
+  Look at this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/goods_doc.rb) to learn more.
 
-Use method `load_schema` in `api_dry`.
+### Trick5 - Auto Generate index/show Actions's Response-Types Based on DB Schema
 
-See this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/auto_gen_doc.rb#L51) for uasge information.
+  Use method `load_schema` in `api_dry`.
+  
+  See this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/examples/auto_gen_doc.rb#L51) for uasge information.
 
 
 ## Troubleshooting
@@ -547,14 +599,14 @@ See this [file](https://github.com/zhandao/zero-rails_openapi/blob/master/docume
 
 ## 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).
+  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
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+  The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Code of Conduct
 
-Everyone interacting in the Zero-OpenApi project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/zhandao/zero-rails_openapi/blob/master/CODE_OF_CONDUCT.md).
+  Everyone interacting in the Zero-OpenApi project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/zhandao/zero-rails_openapi/blob/master/CODE_OF_CONDUCT.md).