zero-rails_openapi 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ade759189024d01051f73655ca7f55d14264598c
-  data.tar.gz: f97aa2a93a2b88af05e8326e5d1ef894a205cc47
+  metadata.gz: 7670c75c3357ce813ab3664c7403386a9e544c58
+  data.tar.gz: 00f1a35580391046946ce002d39ef66dad3d0a71
 SHA512:
-  metadata.gz: 8b9ba73d3704dff23f9e5fc9d515a87ad2e822b7fd08aa9207e9e47d0e47e5ece4ba66bed8514e3465e87ddf761060ed73c2f6cfb8c79be7438a4f7ebe5452eb
-  data.tar.gz: eb6048d787fbc7f3001e2fe7b47b999e404282b801741c07248ee0a6516c64a24b8790f5093383aa5f816a902178752fd8f830977ba4ee55dc4fc36f5b7e4fdc
+  metadata.gz: e149d59f5e44dcf5349f980debf0f000345a3bf398fe9084dda7733305af6a99c42b9aed21f2fc87eabda030ca8e24e0c423a10e8ab2617296ad136dd60bea53
+  data.tar.gz: 12e6d7ad092fda104aa439dcf17c64bcb93d5a0e9467c1e5b4a27802d0ff21dc0c4a63c99523958f7bea7f174a877e43a04c0b5d1aad1f446343eb2e46e9a514

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    zero-rails_openapi (1.2.0)
+    zero-rails_openapi (1.3.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -22,12 +22,14 @@ but I dont have enough time now = ▽ =
 - [Configure](#configure)
 - [Usage](#usage)
   - [DSL for documenting your controller](#dsl-for-documenting-your-controller)
-  - [Generate JSON Documentation File](#generate-json-documentation-file)
+  - [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)
-    - [Write DSL Somewhere Else](#trick1-write-the-dsl-somewhere-else)
-    - [DRYing](#trick2-drying)
-    - [Auto Generate Description](#trick3-auto-generate-description)
+    - [Write DSL somewhere else](#trick1---write-the-dsl-somewhere-else)
+    - [Global DRYing](#trick2---global-drying)
+    - [Auto generate description](#trick3---auto-generate-description)
+    - [Skip or Use parameters define in api_dry](#trick4---skip-or-use-parameters-define-in-api_dry)
+    - [Atuo Generate index/show Actions's Responses Based on DB Schema](#trick5)
 - [Troubleshooting](#troubleshooting)
 
 ## About OAS
@@ -66,7 +68,7 @@ This is the simplest configuration example:
 # config/initializers/open_api.rb
 require 'open_api'
 
-OpenApi.configure do |c|
+OpenApi::Config.tap do |c|
   # [REQUIRED] The output location where .json doc file will be written to.
   c.file_output_path = 'public/open_api'
 
@@ -94,7 +96,7 @@ 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)
+For more detailed configuration: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob//examples/open_api.rb)
 
 ## Usage
 
@@ -128,7 +130,7 @@ class Api::V1::ExamplesController < Api::V1::BaseController
     response '567', 'query result export', :pdf, type: File
   end
 
-  open_api :index, '(SUMMARY) this api blah blah ...' do
+  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',
@@ -205,10 +207,15 @@ end
   
   ```ruby
   # method signature
-  open_api method, summary = '', &block
+  open_api method, summary = '', options = { }, &block
   # usage
-  open_api :index, '(SUMMARY) this api blah blah ...' do; end
+  open_api :index, '(SUMMARY) this api blah blah ...', builder: template1 do end
   ```
+  If pass `builder` or `bd` to the third parameter,
+  and `generate_jbuilder_file` in your setting file is set `true`,
+  ZRO will generate JBuilder file by using specified template that you set
+  `template1` in your setting file.  
+  For example, see: [open_api.rb](https://github.com/zhandao/zero-rails_openapi/blob//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)
@@ -272,11 +279,11 @@ parameters, request body, responses, securities, servers.
   header! name, type, schema_hash = { }
   query!  name, type, schema_hash = { }
   # usage
-  header! :'X-Token', String
+  header! :'Token', String
   query!  :done,      Boolean, must_be: false, default: true
   ```
 
-  [**>> 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//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`
@@ -402,7 +409,7 @@ The DSL methods used to generate the components in this block are:
   # or (unrecommended)
   schema :Dog, { id!: Integer, name: String }, dft: { id: 1, name: 'pet' }
   ```
-  *: see: [Type](https://github.com/zhandao/zero-rails_openapi/blob/master/documentation/parameter.md#type)
+  *: see: [Type](https://github.com/zhandao/zero-rails_openapi/blob//parameter.md#type)
 
 ### Generate JSON Documentation File
 
@@ -454,12 +461,11 @@ end
 
 Notes: convention is the file name ends with `_doc.rb`
 
-#### Trick2 - DRYing
+#### Trick2 - Global DRYing
 
-To be written.
+Method `api_dry` is for DRY but its scope is limited to the current controller.
 
-You can look at this [file](https://github.com/zhandao/zero-rails_openapi/blob/masterdocumentation/examples/auto_gen_dsl.rb) at the moment.  
-In general is to use method `api_dry`.
+I have no idea of best practices, But you can look at this [file](https://github.com/zhandao/zero-rails_openapi/blob/masterdocumentation/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
@@ -491,7 +497,23 @@ query :view, String, enum: {
         'cheap goods':         :borrow,
     }
 ```
-Read this [file](https://github.com/zhandao/zero-rails_openapi/blob/masterdocumentation/examples/auto_gen_desc.rb) to learn more.
+Read this [file](https://github.com/zhandao/zero-rails_openapi/blob/examples/auto_gen_desc.rb) to learn more.
+
+#### Trick4 - Skip or Use parameters define in api_dry
+
+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/examples/goods_doc.rb) to learn more.
+
+#### Trick5 - Auto Generate index/show Actions's Responses Based on DB Schema
+
+Use method `load_schema` in `api_dry`.
+
+See this [file](https://github.com/zhandao/zero-rails_openapi/blob/examples/auto_gen_doc.rb#L51) for uasge information.
+
 
 ## Troubleshooting
 

data/documentation/examples/auto_gen_desc.rb

@@ -11,18 +11,21 @@ class V1::GoodsDoc < BaseDoc
          search_type!: 'search field, allows：<br/>'
                # '1/ name<br/>2/ creator,<br/>3/ category<br/>4/ price<br/>'
 
-    # query :view,        String, enum: %w[all online offline get borrow]
+    # Instead of:
+    # query :view,        String, enum: %w[all online offline expensive cheap]
     query :view, String, enum: {
         'all goods (default)': :all,
-        'only online':         :online,
-        'only offline':        :offline,
-        'expensive goods':     :get,
-        'cheap goods':         :borrow,
+                'only online': :online,
+               'only offline': :offline,
+            'expensive goods': :expensive,
+                'cheap goods': :cheap,
     }
     query :search_type, String, enum: %w[name creator category price]
     # Same as:
     # query :search_type, String, desc!: 'search field, allows：<br/>',
     #       enum: %w[name creator category price]
+
+    # TODO: Support `desc: '', auto_desc: true or [:enum, :must_be]`
   end
 
 end

data/documentation/examples/auto_gen_doc.rb

@@ -0,0 +1,86 @@
+require 'open_api/generator'
+
+# Usage: add `include AutoGenDoc` to your base controller.
+module AutoGenDoc
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    def inherited(subclass)
+      super
+      subclass.class_eval do
+        break unless self.name.match? /sController|sDoc/
+        ctrl_path "api/#{self.name.sub('Doc', '').downcase.gsub('::', '/')}" if self.name.match? /sDoc/
+        open_api_dry
+      end
+    end
+
+    private
+
+    def open_api_dry
+      ctrl_path = try(:controller_path) || instance_variable_get('@_ctrl_path')
+      ::OpenApi::Generator.get_actions_by_ctrl_path(ctrl_path)&.each do |action|
+        api_dry action do
+          header! :Token, String, desc: 'user token'
+
+          # Common :index parameters
+          if action == 'index'
+            query :page, Integer, desc: 'page, greater than 1', range: { ge: 1 }, dft: 1
+            query :rows, Integer, desc: 'data count per page',  range: { ge: 1 }, dft: 10
+          end
+
+          # Common :show parameters
+          if action == 'show'
+            path! :id, Integer, desc: 'id'
+          end
+
+          # Common :destroy parameters
+          if action == 'destroy'
+            path! :id, Integer, desc: 'id'
+          end
+
+          # Common :update parameters
+          if action == 'update'
+            path! :id, Integer, desc: 'id'
+          end
+
+          ### Common responses
+          # OAS require at least one response on each api.
+          # default_response 'default response', :json
+          model = Object.const_get(action_path.split('#').first.split('/').last[0..-2].camelize) rescue nil
+          type = action.in?(['index', 'show']) ? Array[load_schema(model)] : String
+          response '200', 'success', :json, type: {
+              code:      { type: Integer, dft: 200 },
+              msg:       { type: String,  dft: 'success' },
+              total:     { type: Integer },
+              timestamp: { type: Integer },
+              language:  { type: String, dft: 'Ruby' },
+              data:      { type: type }
+          }
+
+
+          ### Automatically generate responses based on the agreed error class.
+          #   The business error-class's implementation see:
+          #     https://github.com/zhandao/zero-rails/blob/master/lib/business_error/z_error.rb
+          #   It's usage see:
+          #     https://github.com/zhandao/zero-rails/blob/master/app/controllers/api/v1/base_controller.rb
+          #   Then, the following code will auto generate error responses by
+          #     extracting the specified error classes info, for example,
+          #     in ExamplesError: `mattr_reader :name_not_found, 'can not find the name', 404`
+          #     will generate: `"404": { "description": "can not find the name" }`
+          ###
+          # # api/v1/examples#index => ExamplesError
+          # error_class_name = action_path.split('#').first.split('/').last.camelize.concat('Error')
+          # error_class = Object.const_get(error_class_name) rescue next
+          # errors = error_class.errors
+          # cur_errs = (errors[action.to_sym] || []) + (errors[:private] || [ ]) + (errors[:_public] || [ ])
+          # cur_errs.each do |error|
+          #   info = error_class.send(error, :info)
+          #   response info[:code], info[:msg]
+          # end
+        end
+      end
+    end
+  end
+end

data/documentation/examples/example_output_doc.json

@@ -0,0 +1,2998 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Zero Rails Apis",
+    "version": "0.0.1"
+  },
+  "servers": [
+    {
+      "url": "http://localhost:3000",
+      "description": "Optional server description, e.g. Main (production) server"
+    },
+    {
+      "url": "http://staging_server",
+      "description": "Optional server description, e.g. Internal staging server for testing"
+    }
+  ],
+  "security": [
+    {
+      "ApiKeyAuth": [
+
+      ]
+    }
+  ],
+  "tags": [
+    {
+      "name": "Goods"
+    },
+    {
+      "name": "Permissions"
+    },
+    {
+      "name": "Roles"
+    },
+    {
+      "name": "Categories"
+    },
+    {
+      "name": "Inventories"
+    },
+    {
+      "name": "Stores"
+    },
+    {
+      "name": "Users"
+    }
+  ],
+  "paths": {
+    "/api/v1/goods": {
+      "get": {
+        "description": "Get list of Goods.",
+        "summary": "Get list of Goods.",
+        "operationId": "index",
+        "tags": [
+          "Goods"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "created_start_at",
+            "in": "query",
+            "required": false,
+            "description": "时间起点, YY-MM-DD (HH:MM:SS, 可选)",
+            "schema": {
+              "type": "string",
+              "format": "date-time",
+              "as": "start"
+            }
+          },
+          {
+            "name": "created_end_at",
+            "in": "query",
+            "required": false,
+            "description": "时间终点, YY-MM-DD (HH:MM:SS, 可选)",
+            "schema": {
+              "type": "string",
+              "format": "date-time",
+              "as": "end"
+            }
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "description": "页数，从 1 开始",
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 1
+            }
+          },
+          {
+            "name": "rows",
+            "in": "query",
+            "required": false,
+            "description": "per page, 请求的数据条数",
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 10
+            }
+          },
+          {
+            "name": "view",
+            "in": "query",
+            "required": false,
+            "description": "请求来自的视图，允许值：<br/>1/ 所有物品 (default): all<br/>2/ 上线物品: online<br/>3/ 下线物品: offline",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "all",
+                "online",
+                "offline"
+              ],
+              "default": "all"
+            }
+          },
+          {
+            "name": "search_type",
+            "in": "query",
+            "required": false,
+            "description": "搜索的字段名，允许值：<br/>1/ name<br/>2/ creator<br/>3/ category_name<br/>4/ unit<br/>5/ price",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "name",
+                "creator",
+                "category_name",
+                "unit",
+                "price"
+              ],
+              "as": "field"
+            }
+          },
+          {
+            "name": "export",
+            "in": "query",
+            "required": false,
+            "description": "是否将查询结果导出 Excel 文件",
+            "schema": {
+              "type": "boolean"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "700": {
+            "description": "change online failed"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      },
+      "post": {
+        "summary": "Create a Good, returns id of the good that was created.",
+        "operationId": "create",
+        "tags": [
+          "Goods"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "for creating a good",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "名字"
+                  },
+                  "category_id": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "as": "cate",
+                    "not_permit": true,
+                    "description": "子类 id"
+                  },
+                  "unit": {
+                    "type": "string",
+                    "description": "单位"
+                  },
+                  "price": {
+                    "type": "number",
+                    "format": "float",
+                    "minimum": 0,
+                    "description": "单价"
+                  },
+                  "is_online": {
+                    "type": "boolean",
+                    "description": "是否上线?"
+                  },
+                  "remarks": {
+                    "type": "string",
+                    "description": "其他说明"
+                  },
+                  "pic_path": {
+                    "type": "string",
+                    "format": "url",
+                    "is": "url",
+                    "description": "图片路径"
+                  }
+                },
+                "required": [
+                  "name",
+                  "category_id",
+                  "unit",
+                  "price"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "600": {
+            "description": "create failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "700": {
+            "description": "change online failed"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    },
+    "/api/v1/goods/{id}": {
+      "get": {
+        "summary": "Show a Good.",
+        "operationId": "show",
+        "tags": [
+          "Goods"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "要查询的 id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "700": {
+            "description": "change online failed"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      },
+      "patch": {
+        "summary": "Update a Good.",
+        "operationId": "update",
+        "tags": [
+          "Goods"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "要更新的 id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "for updating a good",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "名字"
+                  },
+                  "category_id": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "as": "cate",
+                    "not_permit": true,
+                    "description": "子类 id"
+                  },
+                  "unit": {
+                    "type": "string",
+                    "description": "单位"
+                  },
+                  "price": {
+                    "type": "number",
+                    "format": "float",
+                    "minimum": 0,
+                    "description": "单价"
+                  },
+                  "remarks": {
+                    "type": "string",
+                    "description": "其他说明"
+                  },
+                  "pic_path": {
+                    "type": "string",
+                    "format": "url",
+                    "is": "url",
+                    "description": "图片路径"
+                  },
+                  "is_online": {
+                    "type": "boolean",
+                    "description": "是否上线"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "601": {
+            "description": "update failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "700": {
+            "description": "change online failed"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      },
+      "delete": {
+        "summary": "Delete a Good.",
+        "operationId": "destroy",
+        "tags": [
+          "Goods"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "要删除的 id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "602": {
+            "description": "destroy failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "700": {
+            "description": "change online failed"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    },
+    "/api/v1/goods/{id}/change_online": {
+      "post": {
+        "summary": "Change online status of Good, will do: is_online = !is_online.",
+        "operationId": "change_online",
+        "tags": [
+          "Goods"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "要上/下线的物品 id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "700": {
+            "description": "change online failed"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    },
+    "/api/v1/permissions": {
+      "get": {
+        "summary": "Get list of Permissions of specified model",
+        "operationId": "index",
+        "tags": [
+          "Permissions"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "model",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "pattern": "^[A-Z]",
+              "default": "User"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "summary": "POST create a Permission",
+        "operationId": "create",
+        "tags": [
+          "Permissions"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "for creating a permission",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "name of permission"
+                  },
+                  "condition": {
+                    "type": "string",
+                    "default": "true",
+                    "description": "暂不必传"
+                  },
+                  "remarks": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "name"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/roles": {
+      "get": {
+        "summary": "Get list of Roles of specified model",
+        "operationId": "index",
+        "tags": [
+          "Roles"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "model",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "pattern": "^[A-Z]",
+              "default": "Admin"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "summary": "POST create a Role",
+        "operationId": "create",
+        "tags": [
+          "Roles"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "for creating a role",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "name of role"
+                  },
+                  "condition": {
+                    "type": "string",
+                    "default": "true",
+                    "description": "暂不必传"
+                  },
+                  "remarks": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "name"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/roles/{id}/permissions": {
+      "post": {
+        "summary": "GET Permissions of specified role",
+        "operationId": "permissions",
+        "tags": [
+          "Roles"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "要查询的 role id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/roles/{id}/permissions/add": {
+      "post": {
+        "summary": "POST add Permissions to specified role",
+        "operationId": "permissions_add",
+        "tags": [
+          "Roles"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "role id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "for adding permissions to role",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "permission_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "integer",
+                      "minimum": 1
+                    },
+                    "minLength": 1
+                  }
+                },
+                "required": [
+                  "permission_ids"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/roles/{id}/permissions/remove": {
+      "post": {
+        "summary": "POST remove Permissions from specified role",
+        "operationId": "permissions_remove",
+        "tags": [
+          "Roles"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "role id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "for removing permissions from the role",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "permission_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "integer",
+                      "minimum": 1
+                    },
+                    "minLength": 1
+                  }
+                },
+                "required": [
+                  "permission_ids"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/categories": {
+      "get": {
+        "summary": "Get list of Categories.",
+        "operationId": "index",
+        "tags": [
+          "Categories"
+        ],
+        "parameters": [
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "description": "偏移量，从 0 开始",
+            "schema": {
+              "type": "integer",
+              "minimum": 1
+            }
+          },
+          {
+            "name": "rows",
+            "in": "query",
+            "required": false,
+            "description": "per page, 请求的数据条数",
+            "schema": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      },
+      "post": {
+        "summary": "Create a Category, returns id of the category that was created.",
+        "operationId": "create",
+        "tags": [
+          "Categories"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "for creating a category",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "名字"
+                  },
+                  "is_smaller": {
+                    "type": "boolean",
+                    "description": "icon name"
+                  },
+                  "icon_name": {
+                    "type": "string",
+                    "description": "是否二级分类?"
+                  },
+                  "base_id": {
+                    "type": "integer",
+                    "description": "一级分类的 id"
+                  }
+                },
+                "required": [
+                  "name",
+                  "is_smaller"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "600": {
+            "description": "create failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    },
+    "/api/v1/category_list": {
+      "get": {
+        "summary": "Get nested list of Categories.",
+        "operationId": "nested_list",
+        "tags": [
+          "Categories"
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    },
+    "/api/v1/categories/{id}": {
+      "patch": {
+        "summary": "Update a Category.",
+        "operationId": "update",
+        "tags": [
+          "Categories"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "要更新的 id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "for creating a category",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "名字"
+                  },
+                  "is_smaller": {
+                    "type": "boolean",
+                    "description": "icon name"
+                  },
+                  "icon_name": {
+                    "type": "string",
+                    "description": "是否二级分类?"
+                  },
+                  "base_id": {
+                    "type": "integer",
+                    "description": "一级分类的 id"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "601": {
+            "description": "update failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      },
+      "delete": {
+        "summary": "Delete a Category.",
+        "operationId": "destroy",
+        "tags": [
+          "Categories"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "要删除的 id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "602": {
+            "description": "destroy failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    },
+    "/api/v1/inventories": {
+      "get": {
+        "description": "Get list of Goods",
+        "summary": "Get list of Inventories.",
+        "operationId": "index",
+        "tags": [
+          "Inventories"
+        ],
+        "parameters": [
+          {
+            "name": "created_start_at",
+            "in": "query",
+            "required": false,
+            "description": "时间起点, YY-MM-DD (HH:MM:SS, 可选)",
+            "schema": {
+              "type": "string",
+              "format": "date-time",
+              "as": "start"
+            }
+          },
+          {
+            "name": "created_end_at",
+            "in": "query",
+            "required": false,
+            "description": "时间终点, YY-MM-DD (HH:MM:SS, 可选)",
+            "schema": {
+              "type": "string",
+              "format": "date-time",
+              "as": "end"
+            }
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "description": "页数，从 1 开始",
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 1
+            }
+          },
+          {
+            "name": "rows",
+            "in": "query",
+            "required": false,
+            "description": "per page, 请求的数据条数",
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 10
+            }
+          },
+          {
+            "name": "store_code",
+            "in": "query",
+            "required": true,
+            "description": "商店代号",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "search_type",
+            "in": "query",
+            "required": false,
+            "description": "搜索的字段名，允许值：<br/>1/ name<br/>2/ creator<br/>3/ category_name<br/>4/ unit<br/>5/ price",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "name",
+                "creator",
+                "category_name",
+                "unit",
+                "price"
+              ],
+              "as": "field"
+            }
+          },
+          {
+            "name": "export",
+            "in": "query",
+            "required": false,
+            "description": "是否将查询结果导出 Excel 文件",
+            "schema": {
+              "type": "boolean"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/v1/stores": {
+      "get": {
+        "summary": "Get list of Stores.",
+        "operationId": "index",
+        "tags": [
+          "Stores"
+        ],
+        "parameters": [
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "description": "偏移量，从 0 开始",
+            "schema": {
+              "type": "integer",
+              "minimum": 1
+            }
+          },
+          {
+            "name": "rows",
+            "in": "query",
+            "required": false,
+            "description": "per page, 请求的数据条数",
+            "schema": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      },
+      "post": {
+        "summary": "Create a Store, returns id of the store that was created.",
+        "operationId": "create",
+        "tags": [
+          "Stores"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "for creating a store",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "description": "商店代号"
+                  },
+                  "addr": {
+                    "type": "string",
+                    "description": "对应的商店地址"
+                  }
+                },
+                "required": [
+                  "code",
+                  "addr"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "600": {
+            "description": "create failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    },
+    "/api/v1/stores/{id}": {
+      "get": {
+        "summary": "Show a Store.",
+        "operationId": "show",
+        "tags": [
+          "Stores"
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      },
+      "patch": {
+        "summary": "Update a Store.",
+        "operationId": "update",
+        "tags": [
+          "Stores"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "要更新的 id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "for updating a store",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "description": "商店代号"
+                  },
+                  "addr": {
+                    "type": "string",
+                    "description": "对应的商店地址"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "601": {
+            "description": "update failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      },
+      "delete": {
+        "summary": "Delete a Store.",
+        "operationId": "destroy",
+        "tags": [
+          "Stores"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "要删除的 id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "602": {
+            "description": "destroy failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    },
+    "/api/v1/users": {
+      "get": {
+        "summary": {
+          "use": [
+            "Token"
+          ]
+        },
+        "operationId": "index",
+        "tags": [
+          "Users"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "created_start_at",
+            "in": "query",
+            "required": false,
+            "description": "时间起点, YY-MM-DD (HH:MM:SS, 可选)",
+            "schema": {
+              "type": "string",
+              "format": "date-time",
+              "as": "start"
+            }
+          },
+          {
+            "name": "created_end_at",
+            "in": "query",
+            "required": false,
+            "description": "时间终点, YY-MM-DD (HH:MM:SS, 可选)",
+            "schema": {
+              "type": "string",
+              "format": "date-time",
+              "as": "end"
+            }
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "description": "页数，从 1 开始",
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 1
+            }
+          },
+          {
+            "name": "rows",
+            "in": "query",
+            "required": false,
+            "description": "per page, 请求的数据条数",
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 10
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      },
+      "post": {
+        "summary": "register",
+        "operationId": "create",
+        "tags": [
+          "Users"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "register",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  },
+                  "password": {
+                    "type": "string"
+                  },
+                  "password_confirmation": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "name",
+                  "password",
+                  "password_confirmation"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "600": {
+            "description": "invalid info"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    },
+    "/api/v1/users/{id}": {
+      "get": {
+        "summary": {
+          "use": [
+            "Token"
+          ]
+        },
+        "operationId": "show",
+        "tags": [
+          "Users"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    },
+    "/api/v1/login": {
+      "post": {
+        "summary": "user login, and get token.",
+        "operationId": "login",
+        "tags": [
+          "Users"
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "login",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "description": "user name"
+                  },
+                  "password": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "name",
+                  "password"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "601": {
+            "description": "admin not found"
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    },
+    "/api/v1/users/{id}/roles": {
+      "get": {
+        "summary": "GET Roles of specified user",
+        "operationId": "roles",
+        "tags": [
+          "Users"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "要查询的 user id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    },
+    "/api/v1/users/{id}/permissions": {
+      "get": {
+        "summary": "GET Permissions of specified user",
+        "operationId": "permissions",
+        "tags": [
+          "Users"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "要查询的 user id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    },
+    "/api/v1/users/{id}/roles/add": {
+      "post": {
+        "summary": "POST add Roles to specified user",
+        "operationId": "roles_add",
+        "tags": [
+          "Users"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "user id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "for adding roles to user",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "role_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "integer",
+                      "minimum": 1
+                    },
+                    "minLength": 1
+                  }
+                },
+                "required": [
+                  "role_ids"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    },
+    "/api/v1/users/{id}/roles/remove": {
+      "post": {
+        "summary": "POST remove Roles from specified user",
+        "operationId": "roles_remove",
+        "tags": [
+          "Users"
+        ],
+        "parameters": [
+          {
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "user id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "for removing roles from the user",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "role_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "integer",
+                      "minimum": 1
+                    },
+                    "minLength": 1
+                  }
+                },
+                "required": [
+                  "role_ids"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "integer",
+                      "default": 200
+                    },
+                    "msg": {
+                      "type": "string",
+                      "default": "success"
+                    },
+                    "total": {
+                      "type": "integer"
+                    },
+                    "timestamp": {
+                      "type": "integer",
+                      "format": "time",
+                      "is": "time"
+                    },
+                    "language": {
+                      "type": "string",
+                      "default": "Ruby"
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "param validation failure"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuth": {
+        "type": "apiKey",
+        "name": "server_token",
+        "in": "query"
+      }
+    }
+  }
+}