zero-rails_openapi 1.3.3 → 1.4.0

data/documentation/examples/auto_gen_desc.rb

@@ -1,31 +1,29 @@
 class V1::GoodsDoc < BaseDoc
-
-  open_api :index, 'Get list of Goods.' do
-    desc 'listing Goods',
-         view!: 'search view, allows:：<br/>',
+  api :index, 'GET list of goods.' do
+    desc 'listing goods',
+         view!: 'search view, allows:<br/>',
                # '1/ all goods (default)：all<br/>' \
                # '2/ only online：online<br/>' \
                # '3/ only offline：offline<br/>' \
                # '4/ expensive goods：expensive<br/>' \
                # '5/ cheap goods：cheap<br/>',
-         search_type!: 'search field, allows：<br/>'
+         search_type!: 'search field, allows:<br/>'
                # '1/ name<br/>2/ creator,<br/>3/ category<br/>4/ price<br/>'
 
     # Instead of:
-    # query :view,        String, enum: %w[all online offline expensive cheap]
+    # 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': :expensive,
-                'cheap goods': :cheap,
+                'cheap goods': :cheap
     }
-    query :search_type, String, enum: %w[name creator category price]
+    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]
+    #       enum: %w[ name creator category price ]
 
-    # TODO: Support `desc: '', auto_desc: true or [:enum, :must_be]`
+    # TODO: Support `desc: '', auto_desc: true or %i[ enum must_be ]`
   end
-
 end

data/documentation/examples/auto_gen_doc.rb

@@ -11,7 +11,7 @@ module AutoGenDoc
       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/
+        ctrl_path self.name.sub('Doc', '').downcase.gsub('::', '/') if self.name.match?(/sDoc/)
         open_api_dry
       end
     end
@@ -49,7 +49,7 @@ module AutoGenDoc
           # 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
+          type = action.in?(%w[ index show ]) ? Array[load_schema(model)] : String
           response '200', 'success', :json, type: {
               code:      { type: Integer, dft: 200 },
               msg:       { type: String,  dft: 'success' },
@@ -82,4 +82,4 @@ module AutoGenDoc
       end
     end
   end
-end
+end

data/documentation/examples/examples_controller.rb

@@ -2,51 +2,49 @@ class Api::V1::ExamplesController < Api::V1::BaseController
   apis_tag name: 'ExampleTagName', desc: 'ExamplesController\'s APIs'
 
   components do
-    schema :Dog => [{
-                         id!: Integer,
-                         name: { type: String, must_be: 'zhandao', desc: 'name' }
-                     }, # this is schema type, see:
-                     dft: { id: 1, name: 'pet' }]
-    # schema :Dog         => [ String, dft: { id: 1, name: 'pet' } ]
-    query! :QueryCompUuid => [ :product_uuid, String, desc: 'product uuid' ]
-    path!  :PathCompId    => [ :id, Integer, desc: 'user id' ]
-    resp   :RespComp      => [ 'bad request', :json ]
-    body!  :RqBodyComp    => [ :form ]
+    schema :DogSchema => [ String, dft: 'doge' ]
+    query! :UidQuery  => [ :uid, String, desc: 'user uid' ]
+    path!  :IdPath    => [ :id, Integer, desc: 'product id' ]
+    resp   :BadRqResp => [ 'bad request', :json ]
   end
 
-  api_dry %i[index show], 'common response' do
-    response '567', 'query result export', :pdf, type: File
+
+  api_dry %i[ index show ], 'common parts of :index and :show' do
+    header!  :Token, String
+    response 1000, 'data export', :pdf, type: File
   end
 
-  open_api :index, '(SUMMARY) this api blah blah ...', builder: :template1 do
-    this_api_is_invalid! 'this api is expired!'
-    desc 'Optional multiline or single-line Markdown-formatted description',
-         id:         'user id',
-         email_addr: 'email_addr\'s desc'
-    email = 'zero@rails.org'
 
-    query! :id,         Integer, enum: 0..5,     length: [1, 2], pattern: /^[0-9]$/, range: { gt:0, le:5 }
-    query! :done,       Boolean, must_be: false, default: true,  desc: 'must be false'
-    query  :email_addr, String,  lth: :ge_3,     default: email  # is_a: :email
+  api :index, 'GET examples', use: :Token do
+    this_api_is_invalid! 'do not use!'
+    desc '**GET** list of examples,<br/>and get the status 200.',
+         id:    'user id',
+         email: 'email addr\'s desc'
+    email = 'a@b.c'
 
-    file :pdf, 'desc: the media type is application/pdf'
+    query! :count, Integer, enum: 0..5,     length: [1, 2], pattern: /^[0-9]$/, range: { gt: 0, le: 5 }
+    query! :done,  Boolean, must_be: false, default: true,  desc: 'must be false'
+    query  :email, String,  lth: :ge_3,     default: email  # is_a: :email
+    file   :pdf, 'upload a file: the media type should be application/pdf'
 
-    response :success, 'success response', :json, type: :Dog
+    response :success, 'success response', :json, type: :DogSchema
 
     security :ApiKeyAuth
   end
 
-  open_api :show do
-    param_ref    :PathCompId, :QueryCompUuid
-    response_ref '123' => :RespComp, '223' => :RespComp
+
+  api :show, skip: :Token do
+    param_ref    :IdPath, :UidQuery
+    response_ref 400 => :BadRqResp
   end
 
-  open_api :create do
+
+  api :create do
     form 'for creating a user', data: {
-        :name! =>     { type: String, desc: 'user name' },
+            :name! => String, # <= schema_type is `String`
         :password! => { type: String, pattern: /[0-9]{6,10}/, desc: 'password' },
         # optional
-        :remarks =>   { type: String, desc: 'remarks' },
+          :remarks => { type: String, desc: 'remarks' }, # <= schema_type is `String`, and schema_hash is { desc: '..' }
     }
   end
 end

data/documentation/examples/goods_doc.rb

@@ -1,11 +1,12 @@
 class V2::GoodsDoc < BaseDoc
+  SCHEMA_DRY = { a: 1, b: 2 }
 
-  open_api :index, 'GET list of Goods.', builder: :index, # jbuilder templates is set in initializers/open_api.rb
+  api :index, 'GET list of goods.', builder: :index, # jbuilder templates is set in initializers/open_api.rb
            use: [ 'Token', :page, :rows ] do # use parameters write in AutoGenDoc#api_dry
            # skip: [ 'Token' ] do # you can also skip parameters
-    desc 'listing Goods',
-         view!: 'search view, allows:：<br/>',
-         search_type!: 'search field, allows：<br/>'
+    desc 'listing goods',
+         view!: 'search view, allows:<br/>',
+         search_type!: 'search field, allows:<br/>'
 
     # Single `query`
     query :view, String, enum: {
@@ -14,7 +15,7 @@ class V2::GoodsDoc < BaseDoc
                'only offline': :offline,
             'expensive goods': :expensive,
                 'cheap goods': :cheap,
-    }
+    }, **SCHEMA_DRY # >>> Here is a little trick! <<<
     # Batch `query`
     do_query by: {
         :search_type => { type: String, enum: %w[ name creator category price ] },
@@ -27,7 +28,7 @@ class V2::GoodsDoc < BaseDoc
   end
 
 
-  open_api :create, 'POST create a Good', builder: :success_or_not, use: 'Token' do
+  api :create, 'POST create a good', builder: :success_or_not, use: 'Token' do
     form! 'for creating a good', data: {
                :name! => { type: String,  desc: 'good\'s name' },
         :category_id! => { type: Integer, desc: 'sub_category\'s id', npmt: true, range: { ge: 1 }, as: :cate  },
@@ -45,8 +46,8 @@ class V2::GoodsDoc < BaseDoc
   end
 
 
-  open_api :show, 'GET a Good.', builder: :show, use: [ 'Token', :id ]
+  api :show, 'GET the specified Good.', builder: :show, use: [ 'Token', :id ]
 
 
-  open_api :destroy, 'DELETE a Good.', builder: :success_or_not, use: [ 'Token', :id ]
+  api :destroy, 'DELETE the specified Good.', builder: :success_or_not, use: [ 'Token', :id ]
 end

data/documentation/examples/open_api.rb

@@ -3,23 +3,26 @@ require 'open_api'
 OpenApi::Config.tap do |c|
   # Config DSL
   c.instance_eval do
-    api :zero_rails_api, root_controller: ApiDoc
+    open_api :zero_rails, root_controller: ApiDoc
     info version: '0.0.1', title: 'Zero Rails APIs', description: 'API documentation of Zero-Rails Application.'
     server 'http://localhost:3000', desc: 'Main (production) server'
     server 'http://localhost:3000', desc: 'Internal staging server for testing'
-    security ApiKeyAuth: [ ]
-    security_scheme :ApiKeyAuth, type: 'apiKey', name: 'server_token', in: 'query'
+    bearer_auth :Token
+    global_auth :Token
   end
 
   # [REQUIRED] The location where .json doc file will be output.
   c.file_output_path = 'public/open_api'
 
+  # [Optional] Use this txt instead of running `rails routes`.
+  # c.rails_routes_file = 'config/routes.txt'
+
   # Everything about OAS3 is on https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md
   # Getting started: https://swagger.io/docs/specification/basic-structure/
-  c.register_docs = {
-      homepage_api: {
+  c.open_api_docs = {
+      blog_api: {
           # [REQUIRED] ZRO will scan all the descendants of the root_controller, then generate their docs.
-          root_controller: Api::V1::BaseController,
+          root_controller: ApiController,
 
           # [REQUIRED] Info Object: The info section contains API information
           info: {
@@ -38,7 +41,7 @@ OpenApi::Config.tap do |c|
                   # The URL pointing to the contact information. MUST be in the format of a URL.
                   url: 'http://www.github.com',
                   # The email address of the contact person/organization. MUST be in the format of an email address.
-                  email: 'git@gtihub.com'
+                  email: 'x@y.z'
               },
               # License Object: The license information for the exposed API.
               license: {
@@ -75,13 +78,11 @@ OpenApi::Config.tap do |c|
 
           # Authentication
           #   The securitySchemes and security keywords are used to describe the authentication methods used in your API.
+          #   https://swagger.io/docs/specification/authentication/
           # Security Scheme Object: An object to hold reusable Security Scheme Objects.
-          global_security_schemes: {
-              ApiKeyAuth: {
-                  type: 'apiKey',
-                  name: 'server_token',
-                  in: 'query'
-              }
+          security_schemes: {
+              ApiKeyAuth: { type: 'apiKey', name: 'server_token', in: 'query' },
+              Token: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' }
           },
           # Security Requirement Object
           #   A declaration of which security mechanisms can be used across the API.
@@ -89,7 +90,7 @@ OpenApi::Config.tap do |c|
           #   Only one of the security requirement objects need to be satisfied to authorize a request.
           #   Individual operations can override this definition.
           # see: https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#securityRequirementObject
-          global_security: [{ ApiKeyAuth: [] }],
+          global_security: [{ ApiKeyAuth: [] }, { Token: [] }],
       }
   }
 
@@ -102,9 +103,9 @@ OpenApi::Config.tap do |c|
         json.partial! 'api/base', total: @data.size
         
         json.data do
-          # @data = @data.page(@_page).per(@_rows) if @_page || @_rows
+          # @data = @data.page(@page).per(@rows) if @page || @rows
           # json.array! @data do |datum|
-          json.array! @data.page(@_page).per(@_rows) do |datum|
+          json.array! @data.page(@page).per(@rows) do |datum|
             json.(datum, *datum.show_attrs) if datum.present?
           end
         end
@@ -148,4 +149,14 @@ end
 
 Object.const_set('Boolean', 'boolean') # Support `Boolean` writing in DSL
 
-OpenApi.write_docs generate_files: !Rails.env.production?
+OpenApi.write_docs generate_files: !Rails.env.production?
+
+
+__END__
+
+(1) all the description:
+    CommonMark(http://spec.commonmark.org/) syntax MAY be used for rich text representation.
+(2) all the url could be URL template(?):
+    Variable substitutions will be made when a variable is named in {brackets}.
+    variables: Map Object, A map between a variable name and its value, is used for substitution in the URL template.
+    variables example: https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#server-object-example

data/documentation/examples/output_example.json

@@ -1,41 +1,42 @@
 {
   "openapi": "3.0.0",
   "info": {
-    "title": "Zero Rails Apis",
-    "version": "0.0.1"
+    "version": "0.0.1",
+    "title": "Zero Rails APIs",
+    "description": "API documentation of Zero-Rails Application."
   },
   "servers": [
     {
       "url": "http://localhost:3000",
-      "description": "Optional server description, e.g. Main (production) server"
+      "description": "Main (production) server"
     },
     {
-      "url": "http://staging_server",
-      "description": "Optional server description, e.g. Internal staging server for testing"
+      "url": "http://localhost:3000",
+      "description": "Internal staging server for testing"
     }
   ],
   "security": [
     {
-      "ApiKeyAuth": [
+      "Token": [
 
       ]
     }
   ],
   "tags": [
     {
-      "name": "Goods"
+      "name": "Categories"
     },
     {
-      "name": "Permissions"
+      "name": "Goods"
     },
     {
-      "name": "Roles"
+      "name": "Inventories"
     },
     {
-      "name": "Categories"
+      "name": "Permissions"
     },
     {
-      "name": "Inventories"
+      "name": "Roles"
     },
     {
       "name": "Stores"
@@ -45,46 +46,14 @@
     }
   ],
   "paths": {
-    "/api/v1/goods": {
+    "/api/v1/categories": {
       "get": {
-        "description": "Get list of Goods.",
-        "summary": "Get list of Goods.",
+        "summary": "GET list of categories.",
         "operationId": "index",
         "tags": [
-          "Goods"
+          "Categories"
         ],
         "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",
@@ -106,47 +75,6 @@
               "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": {
@@ -180,7 +108,7 @@
                     "data": {
                       "type": "array",
                       "items": {
-                        "type": "object"
+                        "type": ""
                       }
                     }
                   }
@@ -197,19 +125,16 @@
           "-11": {
             "description": "insufficient permission"
           },
-          "700": {
-            "description": "change online failed"
-          },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       },
       "post": {
-        "summary": "Create a Good, returns id of the good that was created.",
+        "summary": "POST create a category.",
         "operationId": "create",
         "tags": [
-          "Goods"
+          "Categories"
         ],
         "parameters": [
           {
@@ -224,7 +149,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "for creating a good",
+          "description": "for creating the specified category",
           "content": {
             "multipart/form-data": {
               "schema": {
@@ -234,43 +159,22 @@
                     "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": {
+                  "is_smaller": {
                     "type": "boolean",
-                    "description": "是否上线?"
+                    "description": "icon name"
                   },
-                  "remarks": {
+                  "icon_name": {
                     "type": "string",
-                    "description": "其他说明"
+                    "description": "是否二级分类?"
                   },
-                  "pic_path": {
-                    "type": "string",
-                    "format": "url",
-                    "is": "url",
-                    "description": "图片路径"
+                  "base_id": {
+                    "type": "integer",
+                    "description": "一级分类的 id"
                   }
                 },
                 "required": [
                   "name",
-                  "category_id",
-                  "unit",
-                  "price"
+                  "is_smaller"
                 ]
               }
             }
@@ -305,10 +209,7 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
@@ -327,41 +228,18 @@
           "-11": {
             "description": "insufficient permission"
           },
-          "700": {
-            "description": "change online failed"
-          },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       }
     },
-    "/api/v1/goods/{id}": {
+    "/api/v1/categories/list": {
       "get": {
-        "summary": "Show a Good.",
-        "operationId": "show",
+        "summary": "GET nested list of categories.",
+        "operationId": "nested_list",
         "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"
-            }
-          }
+          "Categories"
         ],
         "responses": {
           "200": {
@@ -392,10 +270,7 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
@@ -411,19 +286,18 @@
           "-11": {
             "description": "insufficient permission"
           },
-          "700": {
-            "description": "change online failed"
-          },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
-      },
+      }
+    },
+    "/api/v1/categories/{id}": {
       "patch": {
-        "summary": "Update a Good.",
+        "summary": "PATCH update the specified category.",
         "operationId": "update",
         "tags": [
-          "Goods"
+          "Categories"
         ],
         "parameters": [
           {
@@ -447,7 +321,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "for updating a good",
+          "description": "for updating the specified category",
           "content": {
             "multipart/form-data": {
               "schema": {
@@ -457,36 +331,17 @@
                     "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": "其他说明"
+                  "is_smaller": {
+                    "type": "boolean",
+                    "description": "icon name"
                   },
-                  "pic_path": {
+                  "icon_name": {
                     "type": "string",
-                    "format": "url",
-                    "is": "url",
-                    "description": "图片路径"
+                    "description": "是否二级分类?"
                   },
-                  "is_online": {
-                    "type": "boolean",
-                    "description": "是否上线"
+                  "base_id": {
+                    "type": "integer",
+                    "description": "一级分类的 id"
                   }
                 }
               }
@@ -522,10 +377,7 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
@@ -544,19 +396,16 @@
           "-11": {
             "description": "insufficient permission"
           },
-          "700": {
-            "description": "change online failed"
-          },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       },
       "delete": {
-        "summary": "Delete a Good.",
+        "summary": "DELETE the specified category.",
         "operationId": "destroy",
         "tags": [
-          "Goods"
+          "Categories"
         ],
         "parameters": [
           {
@@ -607,10 +456,7 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
@@ -629,19 +475,17 @@
           "-11": {
             "description": "insufficient permission"
           },
-          "700": {
-            "description": "change online failed"
-          },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       }
     },
-    "/api/v1/goods/{id}/change_online": {
-      "post": {
-        "summary": "Change online status of Good, will do: is_online = !is_online.",
-        "operationId": "change_online",
+    "/api/v1/goods": {
+      "get": {
+        "description": "GET list of goods.",
+        "summary": "GET list of goods.",
+        "operationId": "index",
         "tags": [
           "Goods"
         ],
@@ -656,97 +500,109 @@
             }
           },
           {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "description": "要上/下线的物品 id",
+            "name": "view",
+            "in": "query",
+            "required": false,
+            "description": "请求来自的视图，允许值：<br/>1/ 所有物品 (default): all<br/>2/ 上线物品: online<br/>3/ 下线物品: offline",
             "schema": {
-              "type": "integer"
+              "type": "string",
+              "enum": [
+                "all",
+                "online",
+                "offline"
+              ],
+              "default": "all"
             }
-          }
-        ],
-        "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"
-                      }
-                    }
-                  }
-                }
-              }
+          },
+          {
+            "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"
             }
           },
-          "-1": {
-            "description": "invalid token"
+          {
+            "name": "value",
+            "in": "query",
+            "required": false,
+            "description": "查询词",
+            "schema": {
+              "type": "string"
+            }
           },
-          "-10": {
-            "description": "role verification failed"
+          {
+            "name": "created_start_at",
+            "in": "query",
+            "required": false,
+            "description": "时间起点, YY-MM-DD (HH:MM:SS, 可选)",
+            "schema": {
+              "type": "string",
+              "format": "date-time",
+              "as": "start"
+            }
           },
-          "-11": {
-            "description": "insufficient permission"
+          {
+            "name": "created_end_at",
+            "in": "query",
+            "required": false,
+            "description": "时间终点, YY-MM-DD (HH:MM:SS, 可选)",
+            "schema": {
+              "type": "string",
+              "format": "date-time",
+              "as": "end"
+            }
           },
-          "700": {
-            "description": "change online failed"
+          {
+            "name": "page",
+            "in": "query",
+            "required": false,
+            "description": "页数，从 1 开始",
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 1
+            }
           },
-          "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",
+            "name": "rows",
+            "in": "query",
+            "required": false,
+            "description": "per page, 请求的数据条数",
             "schema": {
-              "type": "string"
+              "type": "integer",
+              "minimum": 1,
+              "default": 10
             }
           },
           {
-            "name": "model",
+            "name": "export",
             "in": "query",
             "required": false,
+            "description": "是否将查询结果导出 Excel 文件",
             "schema": {
-              "type": "string",
-              "pattern": "^[A-Z]",
-              "default": "User"
+              "type": "boolean",
+              "examples": [
+                {
+                  "right_input": {
+                    "value": true
+                  }
+                },
+                {
+                  "wrong_input": {
+                    "value": "wrong input"
+                  }
+                }
+              ]
             }
           }
         ],
@@ -781,21 +637,121 @@
                     "data": {
                       "type": "array",
                       "items": {
-                        "type": "object"
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "integer"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "unit": {
+                            "type": "string"
+                          },
+                          "price": {
+                            "type": "number",
+                            "format": "float"
+                          },
+                          "remarks": {
+                            "type": "string"
+                          },
+                          "pic_path": {
+                            "type": "string"
+                          },
+                          "creator": {
+                            "type": "string"
+                          },
+                          "is_online": {
+                            "type": "boolean"
+                          },
+                          "created_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "updated_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "category_info": {
+                            "type": "object",
+                            "properties": {
+                              "id": {
+                                "type": "integer"
+                              },
+                              "name": {
+                                "type": "string"
+                              },
+                              "base_category_id": {
+                                "type": "integer"
+                              },
+                              "icon_name": {
+                                "type": "string"
+                              },
+                              "deleted_at": {
+                                "type": "string",
+                                "format": "date-time"
+                              }
+                            }
+                          }
+                        }
                       }
                     }
                   }
                 }
               }
             }
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "parameter validation failed"
+          }
+        },
+        "examples": [
+          {
+            "right_input": {
+              "value": {
+                "Token": "Token",
+                "view": "view",
+                "search_type": "search_type",
+                "value": "value",
+                "created_start_at": "created_start_at",
+                "created_end_at": "created_end_at",
+                "page": "page",
+                "rows": "rows",
+                "export": "export"
+              }
+            }
+          },
+          {
+            "wrong_input": {
+              "value": {
+                "Token": null,
+                "view": null,
+                "search_type": null,
+                "value": null,
+                "created_start_at": null,
+                "created_end_at": null,
+                "page": null,
+                "rows": null,
+                "export": null
+              }
+            }
           }
-        }
+        ]
       },
       "post": {
-        "summary": "POST create a Permission",
+        "summary": "POST create a good.",
         "operationId": "create",
         "tags": [
-          "Permissions"
+          "Goods"
         ],
         "parameters": [
           {
@@ -810,7 +766,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "for creating a permission",
+          "description": "for creating the specified good",
           "content": {
             "multipart/form-data": {
               "schema": {
@@ -818,21 +774,69 @@
                 "properties": {
                   "name": {
                     "type": "string",
-                    "description": "name of permission"
+                    "description": "名字"
                   },
-                  "condition": {
+                  "category_id": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "as": "cate",
+                    "not_permit": true,
+                    "description": "子类 id"
+                  },
+                  "unit": {
                     "type": "string",
-                    "default": "true",
-                    "description": "暂不必传"
+                    "description": "单位"
+                  },
+                  "price": {
+                    "type": "number",
+                    "format": "float",
+                    "minimum": 0,
+                    "description": "单价"
+                  },
+                  "is_online": {
+                    "type": "boolean",
+                    "description": "是否上线?"
                   },
                   "remarks": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "其他说明"
+                  },
+                  "pic_path": {
+                    "type": "string",
+                    "format": "url",
+                    "is": "url",
+                    "description": "图片路径"
                   }
                 },
                 "required": [
-                  "name"
+                  "name",
+                  "category_id",
+                  "unit",
+                  "price"
                 ]
-              }
+              },
+              "examples": [
+                {
+                  "right_input": {
+                    "value": {
+                      "name": "good1",
+                      "category_id": 6,
+                      "unit": "unit",
+                      "price": 5.7
+                    }
+                  }
+                },
+                {
+                  "wrong_input": {
+                    "value": {
+                      "name": "good2",
+                      "category_id": 0,
+                      "unit": "unit",
+                      "price": -1
+                    }
+                  }
+                }
+              ]
             }
           }
         },
@@ -865,25 +869,37 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
               }
             }
+          },
+          "600": {
+            "description": "create failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "parameter validation failed"
           }
         }
       }
     },
-    "/api/v1/roles": {
+    "/api/v1/goods/{id}": {
       "get": {
-        "summary": "Get list of Roles of specified model",
-        "operationId": "index",
+        "summary": "GET the specified good.",
+        "operationId": "show",
         "tags": [
-          "Roles"
+          "Goods"
         ],
         "parameters": [
           {
@@ -896,13 +912,12 @@
             }
           },
           {
-            "name": "model",
-            "in": "query",
-            "required": false,
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "要查询的 id",
             "schema": {
-              "type": "string",
-              "pattern": "^[A-Z]",
-              "default": "Admin"
+              "type": "integer"
             }
           }
         ],
@@ -937,21 +952,89 @@
                     "data": {
                       "type": "array",
                       "items": {
-                        "type": "object"
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "integer"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "unit": {
+                            "type": "string"
+                          },
+                          "price": {
+                            "type": "number",
+                            "format": "float"
+                          },
+                          "remarks": {
+                            "type": "string"
+                          },
+                          "pic_path": {
+                            "type": "string"
+                          },
+                          "creator": {
+                            "type": "string"
+                          },
+                          "is_online": {
+                            "type": "boolean"
+                          },
+                          "created_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "updated_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "category_info": {
+                            "type": "object",
+                            "properties": {
+                              "id": {
+                                "type": "integer"
+                              },
+                              "name": {
+                                "type": "string"
+                              },
+                              "base_category_id": {
+                                "type": "integer"
+                              },
+                              "icon_name": {
+                                "type": "string"
+                              },
+                              "deleted_at": {
+                                "type": "string",
+                                "format": "date-time"
+                              }
+                            }
+                          }
+                        }
                       }
                     }
                   }
                 }
               }
             }
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "parameter validation failed"
           }
         }
       },
-      "post": {
-        "summary": "POST create a Role",
-        "operationId": "create",
+      "patch": {
+        "summary": "PATCH update the specified Good.",
+        "operationId": "update",
         "tags": [
-          "Roles"
+          "Goods"
         ],
         "parameters": [
           {
@@ -960,38 +1043,379 @@
             "required": true,
             "description": "user token",
             "schema": {
-              "type": "string"
+              "type": "string"
+            }
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "要更新的 id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "for updating the specified 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": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "601": {
+            "description": "update failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "parameter validation failed"
+          }
+        }
+      },
+      "delete": {
+        "summary": "DELETE the specified 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": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "602": {
+            "description": "destroy failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "parameter validation failed"
+          }
+        }
+      }
+    },
+    "/api/v1/goods/{id}/change_online": {
+      "post": {
+        "summary": "POST change online status of the specified good.",
+        "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": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "700": {
+            "description": "change online failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "parameter validation failed"
+          }
+        }
+      }
+    },
+    "/api/v1/inventories": {
+      "get": {
+        "description": "GET list of inventories.",
+        "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": "value",
+            "in": "query",
+            "required": false,
+            "description": "查询词",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "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/><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"
             }
           }
         ],
-        "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",
@@ -1023,23 +1447,35 @@
                     "data": {
                       "type": "array",
                       "items": {
-                        "type": "object"
+                        "type": ""
                       }
                     }
                   }
                 }
               }
             }
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "parameter validation failed"
           }
         }
       }
     },
-    "/api/v1/roles/{id}/permissions": {
-      "post": {
-        "summary": "GET Permissions of specified role",
-        "operationId": "permissions",
+    "/api/v1/permissions": {
+      "get": {
+        "summary": "GET permissions list of the specified model.",
+        "operationId": "index",
         "tags": [
-          "Roles"
+          "Permissions"
         ],
         "parameters": [
           {
@@ -1052,12 +1488,13 @@
             }
           },
           {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "description": "要查询的 role id",
+            "name": "model",
+            "in": "query",
+            "required": false,
             "schema": {
-              "type": "integer"
+              "type": "string",
+              "pattern": "^[A-Z]",
+              "default": "User"
             }
           }
         ],
@@ -1092,23 +1529,52 @@
                     "data": {
                       "type": "array",
                       "items": {
-                        "type": "object"
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "integer"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "remarks": {
+                            "type": "string"
+                          },
+                          "created_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "updated_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          }
+                        }
                       }
                     }
                   }
                 }
               }
             }
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "parameter validation failed"
           }
         }
-      }
-    },
-    "/api/v1/roles/{id}/permissions/add": {
+      },
       "post": {
-        "summary": "POST add Permissions to specified role",
-        "operationId": "permissions_add",
+        "summary": "PATCH update the specified permission.",
+        "operationId": "create",
         "tags": [
-          "Roles"
+          "Permissions"
         ],
         "parameters": [
           {
@@ -1119,37 +1585,29 @@
             "schema": {
               "type": "string"
             }
-          },
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "description": "role id",
-            "schema": {
-              "type": "integer"
-            }
           }
         ],
         "requestBody": {
           "required": true,
-          "description": "for adding permissions to role",
+          "description": "for updating the specified permission",
           "content": {
             "multipart/form-data": {
               "schema": {
                 "type": "object",
                 "properties": {
-                  "permission_ids": {
-                    "type": "array",
-                    "items": {
-                      "type": "integer",
-                      "minimum": 1
-                    },
-                    "minLength": 1
+                  "name": {
+                    "type": "string",
+                    "description": "name of permission"
+                  },
+                  "condition": {
+                    "type": "string",
+                    "default": "true",
+                    "description": "暂不必传"
+                  },
+                  "remarks": {
+                    "type": "string"
                   }
-                },
-                "required": [
-                  "permission_ids"
-                ]
+                }
               }
             }
           }
@@ -1183,25 +1641,37 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
               }
             }
+          },
+          "600": {
+            "description": "create failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "parameter validation failed"
           }
         }
       }
     },
-    "/api/v1/roles/{id}/permissions/remove": {
-      "post": {
-        "summary": "POST remove Permissions from specified role",
-        "operationId": "permissions_remove",
+    "/api/v1/permissions/{id}": {
+      "delete": {
+        "summary": "DELETE the specified permission.",
+        "operationId": "destroy",
         "tags": [
-          "Roles"
+          "Permissions"
         ],
         "parameters": [
           {
@@ -1217,36 +1687,12 @@
             "name": "id",
             "in": "path",
             "required": true,
-            "description": "role id",
+            "description": "要删除的 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",
@@ -1276,45 +1722,56 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
               }
             }
+          },
+          "602": {
+            "description": "destroy failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "parameter validation failed"
           }
         }
       }
     },
-    "/api/v1/categories": {
+    "/api/v1/roles": {
       "get": {
-        "summary": "Get list of Categories.",
+        "summary": "GET roles list of the specified model",
         "operationId": "index",
         "tags": [
-          "Categories"
+          "Roles"
         ],
         "parameters": [
           {
-            "name": "page",
-            "in": "query",
-            "required": false,
-            "description": "偏移量，从 0 开始",
+            "name": "Token",
+            "in": "header",
+            "required": true,
+            "description": "user token",
             "schema": {
-              "type": "integer",
-              "minimum": 1
+              "type": "string"
             }
           },
           {
-            "name": "rows",
+            "name": "model",
             "in": "query",
             "required": false,
-            "description": "per page, 请求的数据条数",
             "schema": {
-              "type": "integer",
-              "minimum": 1
+              "type": "string",
+              "pattern": "^[A-Z]",
+              "default": "User"
             }
           }
         ],
@@ -1349,7 +1806,29 @@
                     "data": {
                       "type": "array",
                       "items": {
-                        "type": "object"
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "integer"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "remarks": {
+                            "type": "string"
+                          },
+                          "base_role_id": {
+                            "type": "integer"
+                          },
+                          "created_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "updated_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          }
+                        }
                       }
                     }
                   }
@@ -1367,15 +1846,15 @@
             "description": "insufficient permission"
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       },
       "post": {
-        "summary": "Create a Category, returns id of the category that was created.",
+        "summary": "POST create a role",
         "operationId": "create",
         "tags": [
-          "Categories"
+          "Roles"
         ],
         "parameters": [
           {
@@ -1390,7 +1869,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "for creating a category",
+          "description": "for creating the specified role",
           "content": {
             "multipart/form-data": {
               "schema": {
@@ -1398,24 +1877,19 @@
                 "properties": {
                   "name": {
                     "type": "string",
-                    "description": "名字"
-                  },
-                  "is_smaller": {
-                    "type": "boolean",
-                    "description": "icon name"
+                    "description": "name of role"
                   },
-                  "icon_name": {
+                  "condition": {
                     "type": "string",
-                    "description": "是否二级分类?"
+                    "default": "true",
+                    "description": "暂不必传"
                   },
-                  "base_id": {
-                    "type": "integer",
-                    "description": "一级分类的 id"
+                  "remarks": {
+                    "type": "string"
                   }
                 },
                 "required": [
-                  "name",
-                  "is_smaller"
+                  "name"
                 ]
               }
             }
@@ -1450,10 +1924,7 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
@@ -1473,17 +1944,37 @@
             "description": "insufficient permission"
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       }
     },
-    "/api/v1/category_list": {
+    "/api/v1/roles/{id}": {
       "get": {
-        "summary": "Get nested list of Categories.",
-        "operationId": "nested_list",
+        "summary": "GET the specified role.",
+        "operationId": "show",
         "tags": [
-          "Categories"
+          "Roles"
+        ],
+        "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": {
@@ -1516,7 +2007,29 @@
                     "data": {
                       "type": "array",
                       "items": {
-                        "type": "object"
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "integer"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "remarks": {
+                            "type": "string"
+                          },
+                          "base_role_id": {
+                            "type": "integer"
+                          },
+                          "created_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "updated_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          }
+                        }
                       }
                     }
                   }
@@ -1534,17 +2047,15 @@
             "description": "insufficient permission"
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
-      }
-    },
-    "/api/v1/categories/{id}": {
-      "patch": {
-        "summary": "Update a Category.",
-        "operationId": "update",
+      },
+      "delete": {
+        "summary": "DELETE the specified role.",
+        "operationId": "destroy",
         "tags": [
-          "Categories"
+          "Roles"
         ],
         "parameters": [
           {
@@ -1560,41 +2071,12 @@
             "name": "id",
             "in": "path",
             "required": true,
-            "description": "要更新的 id",
+            "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",
@@ -1624,18 +2106,15 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
               }
             }
           },
-          "601": {
-            "description": "update failed"
+          "602": {
+            "description": "destroy failed"
           },
           "-1": {
             "description": "invalid token"
@@ -1647,15 +2126,17 @@
             "description": "insufficient permission"
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
-      },
-      "delete": {
-        "summary": "Delete a Category.",
-        "operationId": "destroy",
+      }
+    },
+    "/api/v1/roles/{id}/permissions": {
+      "get": {
+        "summary": "GET permissions of specified role",
+        "operationId": "permissions",
         "tags": [
-          "Categories"
+          "Roles"
         ],
         "parameters": [
           {
@@ -1671,7 +2152,7 @@
             "name": "id",
             "in": "path",
             "required": true,
-            "description": "要删除的 id",
+            "description": "要查询的 role id",
             "schema": {
               "type": "integer"
             }
@@ -1706,19 +2187,13 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
               }
             }
           },
-          "602": {
-            "description": "destroy failed"
-          },
           "-1": {
             "description": "invalid token"
           },
@@ -1729,100 +2204,62 @@
             "description": "insufficient permission"
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       }
     },
-    "/api/v1/inventories": {
-      "get": {
-        "description": "Get list of Goods",
-        "summary": "Get list of Inventories.",
-        "operationId": "index",
+    "/api/v1/roles/{id}/permissions/modify": {
+      "post": {
+        "summary": "POST modify permissions to the specified role and then save to db",
+        "operationId": "permissions_modify",
         "tags": [
-          "Inventories"
+          "Roles"
         ],
         "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",
+            "name": "Token",
+            "in": "header",
             "required": true,
-            "description": "商店代号",
+            "description": "user token",
             "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 文件",
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "role id",
             "schema": {
-              "type": "boolean"
+              "type": "integer"
             }
           }
         ],
+        "requestBody": {
+          "required": true,
+          "description": "for modifying permissions to the specified role",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "permission_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "integer",
+                      "minimum": 1
+                    },
+                    "minItems": 1
+                  }
+                },
+                "required": [
+                  "permission_ids"
+                ]
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
             "description": "success",
@@ -1852,22 +2289,31 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
               }
             }
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "parameter validation failed"
           }
         }
       }
     },
     "/api/v1/stores": {
       "get": {
-        "summary": "Get list of Stores.",
+        "summary": "GET list of stores.",
         "operationId": "index",
         "tags": [
           "Stores"
@@ -1925,7 +2371,18 @@
                     "data": {
                       "type": "array",
                       "items": {
-                        "type": "object"
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "integer"
+                          },
+                          "code": {
+                            "type": "string"
+                          },
+                          "addr": {
+                            "type": "string"
+                          }
+                        }
                       }
                     }
                   }
@@ -1943,12 +2400,12 @@
             "description": "insufficient permission"
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       },
       "post": {
-        "summary": "Create a Store, returns id of the store that was created.",
+        "summary": "POST create a store.",
         "operationId": "create",
         "tags": [
           "Stores"
@@ -1966,7 +2423,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "for creating a store",
+          "description": "for creating the specified store",
           "content": {
             "multipart/form-data": {
               "schema": {
@@ -2018,10 +2475,7 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
@@ -2041,18 +2495,29 @@
             "description": "insufficient permission"
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       }
     },
     "/api/v1/stores/{id}": {
       "get": {
-        "summary": "Show a Store.",
+        "summary": "GET the specified store.",
         "operationId": "show",
         "tags": [
           "Stores"
         ],
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "要查询的 id",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
         "responses": {
           "200": {
             "description": "success",
@@ -2084,7 +2549,18 @@
                     "data": {
                       "type": "array",
                       "items": {
-                        "type": "object"
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "integer"
+                          },
+                          "code": {
+                            "type": "string"
+                          },
+                          "addr": {
+                            "type": "string"
+                          }
+                        }
                       }
                     }
                   }
@@ -2102,12 +2578,12 @@
             "description": "insufficient permission"
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       },
       "patch": {
-        "summary": "Update a Store.",
+        "summary": "POST update the specified store.",
         "operationId": "update",
         "tags": [
           "Stores"
@@ -2134,7 +2610,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "for updating a store",
+          "description": "for updating the specified store",
           "content": {
             "multipart/form-data": {
               "schema": {
@@ -2152,7 +2628,86 @@
               }
             }
           }
-        },
+        },
+        "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": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "601": {
+            "description": "update failed"
+          },
+          "-1": {
+            "description": "invalid token"
+          },
+          "-10": {
+            "description": "role verification failed"
+          },
+          "-11": {
+            "description": "insufficient permission"
+          },
+          "400": {
+            "description": "parameter validation failed"
+          }
+        }
+      },
+      "delete": {
+        "summary": "DELETE the specified 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",
@@ -2182,18 +2737,15 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
               }
             }
           },
-          "601": {
-            "description": "update failed"
+          "602": {
+            "description": "destroy failed"
           },
           "-1": {
             "description": "invalid token"
@@ -2205,15 +2757,17 @@
             "description": "insufficient permission"
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
-      },
-      "delete": {
-        "summary": "Delete a Store.",
-        "operationId": "destroy",
+      }
+    },
+    "/api/v1/u/{name}": {
+      "get": {
+        "summary": "GET the specified user by name.",
+        "operationId": "show_via_name",
         "tags": [
-          "Stores"
+          "Users"
         ],
         "parameters": [
           {
@@ -2226,12 +2780,12 @@
             }
           },
           {
-            "name": "id",
+            "name": "name",
             "in": "path",
             "required": true,
-            "description": "要删除的 id",
+            "description": "user name",
             "schema": {
-              "type": "integer"
+              "type": "string"
             }
           }
         ],
@@ -2264,41 +2818,22 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
               }
             }
           },
-          "602": {
-            "description": "destroy failed"
-          },
-          "-1": {
-            "description": "invalid token"
-          },
-          "-10": {
-            "description": "role verification failed"
-          },
-          "-11": {
-            "description": "insufficient permission"
-          },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       }
     },
     "/api/v1/users": {
       "get": {
-        "summary": {
-          "use": [
-            "Token"
-          ]
-        },
+        "summary": "GET list of users.",
         "operationId": "index",
         "tags": [
           "Users"
@@ -2313,28 +2848,6 @@
               "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",
@@ -2389,7 +2902,36 @@
                     "data": {
                       "type": "array",
                       "items": {
-                        "type": "object"
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "integer"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "password_digest": {
+                            "type": "string"
+                          },
+                          "email": {
+                            "type": "string"
+                          },
+                          "phone_number": {
+                            "type": "string"
+                          },
+                          "deleted_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "created_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "updated_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          }
+                        }
                       }
                     }
                   }
@@ -2398,30 +2940,19 @@
             }
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       },
       "post": {
-        "summary": "register",
+        "summary": "POST user register",
         "operationId": "create",
         "tags": [
           "Users"
         ],
-        "parameters": [
-          {
-            "name": "Token",
-            "in": "header",
-            "required": true,
-            "description": "user token",
-            "schema": {
-              "type": "string"
-            }
-          }
-        ],
         "requestBody": {
           "required": true,
-          "description": "register",
+          "description": "for registering user",
           "content": {
             "multipart/form-data": {
               "schema": {
@@ -2435,6 +2966,12 @@
                   },
                   "password_confirmation": {
                     "type": "string"
+                  },
+                  "email": {
+                    "type": "string"
+                  },
+                  "phone_number": {
+                    "type": "string"
                   }
                 },
                 "required": [
@@ -2475,32 +3012,107 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
               }
             }
           },
-          "600": {
+          "700": {
+            "description": "invalid info"
+          },
+          "701": {
             "description": "invalid info"
           },
+          "702": {
+            "description": "repeated info"
+          },
+          "400": {
+            "description": "parameter validation failed"
+          }
+        }
+      }
+    },
+    "/api/v1/users/login": {
+      "post": {
+        "summary": "POST user login.",
+        "operationId": "login",
+        "tags": [
+          "Users"
+        ],
+        "requestBody": {
+          "required": true,
+          "description": "for user 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": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "800": {
+            "description": "login failed"
+          },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       }
     },
     "/api/v1/users/{id}": {
       "get": {
-        "summary": {
-          "use": [
-            "Token"
-          ]
-        },
+        "summary": "GET the specified user.",
         "operationId": "show",
         "tags": [
           "Users"
@@ -2556,7 +3168,36 @@
                     "data": {
                       "type": "array",
                       "items": {
-                        "type": "object"
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "integer"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "password_digest": {
+                            "type": "string"
+                          },
+                          "email": {
+                            "type": "string"
+                          },
+                          "phone_number": {
+                            "type": "string"
+                          },
+                          "deleted_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "created_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          },
+                          "updated_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          }
+                        }
                       }
                     }
                   }
@@ -2565,38 +3206,60 @@
             }
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
-      }
-    },
-    "/api/v1/login": {
-      "post": {
-        "summary": "user login, and get token.",
-        "operationId": "login",
+      },
+      "patch": {
+        "summary": "PATCH update the specified User.",
+        "operationId": "update",
         "tags": [
           "Users"
         ],
+        "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": "login",
+          "description": "for updating the specified user",
           "content": {
             "multipart/form-data": {
               "schema": {
                 "type": "object",
                 "properties": {
                   "name": {
-                    "type": "string",
-                    "description": "user name"
+                    "type": "string"
                   },
                   "password": {
                     "type": "string"
+                  },
+                  "password_confirmation": {
+                    "type": "string"
+                  },
+                  "email": {
+                    "type": "string"
+                  },
+                  "phone_number": {
+                    "type": "string"
                   }
-                },
-                "required": [
-                  "name",
-                  "password"
-                ]
+                }
               }
             }
           }
@@ -2630,29 +3293,21 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
               }
             }
           },
-          "601": {
-            "description": "admin not found"
-          },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
-      }
-    },
-    "/api/v1/users/{id}/roles": {
-      "get": {
-        "summary": "GET Roles of specified user",
-        "operationId": "roles",
+      },
+      "delete": {
+        "summary": "DELETE the specified User.",
+        "operationId": "destroy",
         "tags": [
           "Users"
         ],
@@ -2670,7 +3325,7 @@
             "name": "id",
             "in": "path",
             "required": true,
-            "description": "要查询的 user id",
+            "description": "要删除的 id",
             "schema": {
               "type": "integer"
             }
@@ -2705,10 +3360,7 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
@@ -2716,14 +3368,14 @@
             }
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       }
     },
     "/api/v1/users/{id}/permissions": {
       "get": {
-        "summary": "GET Permissions of specified user",
+        "summary": "GET permissions of the specified user",
         "operationId": "permissions",
         "tags": [
           "Users"
@@ -2777,10 +3429,7 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
@@ -2788,15 +3437,15 @@
             }
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       }
     },
-    "/api/v1/users/{id}/roles/add": {
-      "post": {
-        "summary": "POST add Roles to specified user",
-        "operationId": "roles_add",
+    "/api/v1/users/{id}/roles": {
+      "get": {
+        "summary": "GET roles of the specified user",
+        "operationId": "roles",
         "tags": [
           "Users"
         ],
@@ -2814,36 +3463,12 @@
             "name": "id",
             "in": "path",
             "required": true,
-            "description": "user id",
+            "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",
@@ -2873,10 +3498,7 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
@@ -2884,15 +3506,15 @@
             }
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       }
     },
-    "/api/v1/users/{id}/roles/remove": {
+    "/api/v1/users/{id}/roles/modify": {
       "post": {
-        "summary": "POST remove Roles from specified user",
-        "operationId": "roles_remove",
+        "summary": "POST modify roles to the specified user",
+        "operationId": "roles_modify",
         "tags": [
           "Users"
         ],
@@ -2918,7 +3540,7 @@
         ],
         "requestBody": {
           "required": true,
-          "description": "for removing roles from the user",
+          "description": "for modifying roles to the specified user",
           "content": {
             "multipart/form-data": {
               "schema": {
@@ -2930,7 +3552,7 @@
                       "type": "integer",
                       "minimum": 1
                     },
-                    "minLength": 1
+                    "minItems": 1
                   }
                 },
                 "required": [
@@ -2969,10 +3591,7 @@
                       "default": "Ruby"
                     },
                     "data": {
-                      "type": "array",
-                      "items": {
-                        "type": "object"
-                      }
+                      "type": "string"
                     }
                   }
                 }
@@ -2980,7 +3599,7 @@
             }
           },
           "400": {
-            "description": "param validation failure"
+            "description": "parameter validation failed"
           }
         }
       }
@@ -2988,10 +3607,10 @@
   },
   "components": {
     "securitySchemes": {
-      "ApiKeyAuth": {
-        "type": "apiKey",
-        "name": "server_token",
-        "in": "query"
+      "Token": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
       }
     }
   }