diff --git a/docs/README.md b/docs/README.md
index fe98c14fd8..d82edc688b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -5,3 +5,16 @@
 	docker run -d -p 8081:8080 swaggerapi/swagger-editor
 
 swagger文档，https://swagger.io/docs/specification/2-0/basic-structure/
+
+编辑测试：
+
+1. 首先启动swagger-ui
+
+    sudo docker pull swaggerapi/swagger-ui
+    sudo docker run -p 80:8080 swaggerapi/swagger-ui
+
+2. 用python启动本地的http server，这是允许CORS的SimpleHTTPServer，监听在8000端口
+
+   python server.py
+
+3. 用浏览器打开swagger-ui的URL：http://<swagger_ui_host>?url=http://<simple_http_server_host>:8000/index.yaml
diff --git a/docs/identity/auth_v2.yaml b/docs/identity/auth_v2.yaml
new file mode 100644
index 0000000000..8a2e12a407
--- /dev/null
+++ b/docs/identity/auth_v2.yaml
@@ -0,0 +1,16 @@
+post:
+  summary: keystone v2认证接口，通过用户名／密码或者token认证
+  parameters:
+    - name: auth
+      in: body
+      required: true
+      schema:
+        type: object
+        $ref: "../schemas/auth.yaml#/Auth2Input"
+  responses:
+    200:
+      description: keystone v2认证信息
+      schema:
+        $ref: "../schemas/auth.yaml#/Auth2Response"
+  tags:
+    - authentication
diff --git a/docs/identity/auth_v3.yaml b/docs/identity/auth_v3.yaml
new file mode 100644
index 0000000000..b6e1ce517a
--- /dev/null
+++ b/docs/identity/auth_v3.yaml
@@ -0,0 +1,27 @@
+get:
+  summary: keystone v3 token验证API
+  parameters:
+    - $ref: '../parameters/auth.yaml#/token3'
+  responses:
+    200:
+      description: keystone v3 token信息
+      schema:
+        $ref: "../schemas/auth.yaml#/Auth3Response"
+  tags:
+    - authentication
+
+post:
+  summary: keystone v3认证API
+  parameters:
+    - name: auth
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/auth.yaml#/Auth3Input"
+  responses:
+    200:
+      description: keystone v3 token信息
+      schema:
+        $ref: "../schemas/auth.yaml#/Auth3Response"
+  tags:
+    - authentication
diff --git a/docs/identity/credentials.yaml b/docs/identity/credentials.yaml
new file mode 100644
index 0000000000..ebb86cd7f6
--- /dev/null
+++ b/docs/identity/credentials.yaml
@@ -0,0 +1,12 @@
+get:
+  summary: 按指定条件列出用户credentails
+  parameters:
+    - $ref: '../parameters/credential.yaml#/type'
+    - $ref: '../parameters/credential.yaml#/user_id'
+  responses:
+    200:
+      description: 用户credential列表信息
+      schema:
+        $ref: "../schemas/credential.yaml#/CredentialListResponse"
+  tags:
+    - credentials
diff --git a/docs/identity/domain.yaml b/docs/identity/domain.yaml
new file mode 100644
index 0000000000..68ccf509a3
--- /dev/null
+++ b/docs/identity/domain.yaml
@@ -0,0 +1,40 @@
+get:
+  summary: 获得指定域的详情
+  parameters:
+    - $ref: '../parameters/domain.yaml#/domain_id'
+  responses:
+    200:
+      description: 域信息
+      schema:
+        $ref: "../schemas/domain.yaml#/DomainGetResponse"
+  tags:
+    - domains
+
+put:
+  summary: 更新指定域的字段
+  parameters:
+    - $ref: '../parameters/domain.yaml#/domain_id'
+    - name: domain
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/domain.yaml#/DomainPutRequestInput"
+  responses:
+    200:
+      description: 域信息
+      schema:
+        $ref: "../schemas/domain.yaml#/DomainGetResponse"
+  tags:
+    - domains
+
+delete:
+  summary: 删除指定的域
+  parameters:
+    - $ref: '../parameters/domain.yaml#/domain_id'
+  responses:
+    200:
+      description: 被删除的域信息
+      schema:
+        $ref: "../schemas/domain.yaml#/DomainGetResponse"
+  tags:
+    - domains
diff --git a/docs/identity/domains.yaml b/docs/identity/domains.yaml
new file mode 100644
index 0000000000..4efaa0ffbd
--- /dev/null
+++ b/docs/identity/domains.yaml
@@ -0,0 +1,29 @@
+get:
+  summary: 按指定条件列出域
+  parameters:
+    - $ref: '../parameters/common.yaml#/offset'
+    - $ref: '../parameters/common.yaml#/limit'
+  responses:
+    200:
+      description: 域列表信息
+      schema:
+        $ref: "../schemas/domain.yaml#/DomainListResponse"
+  tags:
+    - domains
+
+post:
+  summary: 新建域
+  parameters:
+    - name: domain
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/domain.yaml#/DomainCreateInput"
+  responses:
+    200:
+      description: 域信息
+      schema:
+        $ref: "../schemas/domain.yaml#/DomainGetResponse"
+  tags:
+    - domains
+
diff --git a/docs/identity/endpoint.yaml b/docs/identity/endpoint.yaml
new file mode 100644
index 0000000000..f9a0be201e
--- /dev/null
+++ b/docs/identity/endpoint.yaml
@@ -0,0 +1,40 @@
+get:
+  summary: 获得指定接入点的详情
+  parameters:
+    - $ref: '../parameters/endpoint.yaml#/endpoint_id'
+  responses:
+    200:
+      description: 接入点信息
+      schema:
+        $ref: "../schemas/endpoint.yaml#/EndpointGetResponse"
+  tags:
+    - endpoints
+
+put:
+  summary: 更新指定接入点的属性
+  parameters:
+    - $ref: '../parameters/endpoint.yaml#/endpoint_id'
+    - name: endpoint
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/endpoint.yaml#/EndpointPutRequestInput"
+  responses:
+    200:
+      description: 接入点信息
+      schema:
+        $ref: "../schemas/endpoint.yaml#/EndpointGetResponse"
+  tags:
+    - endpoints
+
+delete:
+  summary: 删除指定接入点
+  parameters:
+    - $ref: '../parameters/endpoint.yaml#/endpoint_id'
+  responses:
+    200:
+      description: 被删除的接入点信息
+      schema:
+        $ref: "../schemas/endpoint.yaml#/EndpointGetResponse"
+  tags:
+    - endpoints
diff --git a/docs/identity/endpoints.yaml b/docs/identity/endpoints.yaml
new file mode 100644
index 0000000000..d501031c14
--- /dev/null
+++ b/docs/identity/endpoints.yaml
@@ -0,0 +1,28 @@
+get:
+  summary: 按指定条件列出服务接入点
+  parameters:
+    - $ref: '../parameters/common.yaml#/offset'
+    - $ref: '../parameters/common.yaml#/limit'
+  responses:
+    200:
+      description: 接入点列表信息
+      schema:
+        $ref: "../schemas/endpoint.yaml#/EndpointListResponse"
+  tags:
+    - endpoints
+
+post:
+  summary: 新建一个接入点
+  parameters:
+    - name: endpoint
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/endpoint.yaml#/EndpointCreateInput"
+  responses:
+    200:
+      description: 接入点信息
+      schema:
+        $ref: "../schemas/endpoint.yaml#/EndpointGetResponse"
+  tags:
+    - endpoints
diff --git a/docs/identity/group.yaml b/docs/identity/group.yaml
new file mode 100644
index 0000000000..ca751d72b2
--- /dev/null
+++ b/docs/identity/group.yaml
@@ -0,0 +1,40 @@
+get:
+  summary: 获得指定组的详情
+  parameters:
+    - $ref: '../parameters/group.yaml#/group_id'
+  responses:
+    200:
+      description: 组信息
+      schema:
+        $ref: "../schemas/group.yaml#/GroupGetResponse"
+  tags:
+    - groups
+
+put:
+  summary: 更新指定组的信息
+  parameters:
+    - $ref: '../parameters/group.yaml#/group_id'
+    - name: group
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/group.yaml#/GroupPutRequestInput"
+  responses:
+    200:
+      description: 组信息
+      schema:
+        $ref: "../schemas/group.yaml#/GroupGetResponse"
+  tags:
+    - groups
+
+delete:
+  summary: 删除指定组
+  parameters:
+    - $ref: '../parameters/group.yaml#/group_id'
+  responses:
+    200:
+      description: 被删除的组信息
+      schema:
+        $ref: "../schemas/group.yaml#/GroupGetResponse"
+  tags:
+    - groups
diff --git a/docs/identity/groups.yaml b/docs/identity/groups.yaml
new file mode 100644
index 0000000000..e0dc140ab4
--- /dev/null
+++ b/docs/identity/groups.yaml
@@ -0,0 +1,31 @@
+get:
+  summary: 按指定条件列出组
+  parameters:
+    - $ref: '../parameters/common.yaml#/offset'
+    - $ref: '../parameters/common.yaml#/limit'
+    - $ref: '../parameters/common.yaml#/scope'
+    - $ref: '../parameters/identity.yaml#/project_domain'
+  responses:
+    200:
+      description: 组列表信息
+      schema:
+        $ref: "../schemas/group.yaml#/GroupListResponse"
+  tags:
+    - groups
+
+post:
+  summary: 新建一个本地组
+  parameters:
+    - name: group
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/group.yaml#/GroupCreateInput"
+  responses:
+    200:
+      description: 组信息
+      schema:
+        $ref: "../schemas/group.yaml#/GroupGetResponse"
+  tags:
+    - groups
+
diff --git a/docs/identity/groupuser.yaml b/docs/identity/groupuser.yaml
new file mode 100644
index 0000000000..0e7d42669d
--- /dev/null
+++ b/docs/identity/groupuser.yaml
@@ -0,0 +1,21 @@
+put:
+  summary: 将用户加入组
+  parameters:
+    - $ref: '../parameters/identity.yaml#/group_id'
+    - $ref: '../parameters/identity.yaml#/user_id'
+  responses:
+    200:
+      description: 成功
+  tags:
+    - users
+
+delete:
+  summary: 将用户从组中删除
+  parameters:
+    - $ref: '../parameters/identity.yaml#/group_id'
+    - $ref: '../parameters/identity.yaml#/user_id'
+  responses:
+    200:
+      description: 成功
+  tags:
+    - users
diff --git a/docs/identity/identity_provider.yaml b/docs/identity/identity_provider.yaml
new file mode 100644
index 0000000000..9fbd174ccd
--- /dev/null
+++ b/docs/identity/identity_provider.yaml
@@ -0,0 +1,40 @@
+get:
+  summary: 获得指定认证源的详情
+  parameters:
+    - $ref: '../parameters/identity_provider.yaml#/idp_id'
+  responses:
+    200:
+      description: 认证源信息
+      schema:
+        $ref: "../schemas/identity_provider.yaml#/IdpGetResponse"
+  tags:
+    - identity_providers
+
+put:
+  summary: 更新指定认证源的字段
+  parameters:
+    - $ref: '../parameters/identity_provider.yaml#/idp_id'
+    - name: identity_provider
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/identity_provider.yaml#/IdpPutRequestInput"
+  responses:
+    200:
+      description: 认证源信息
+      schema:
+        $ref: "../schemas/identity_provider.yaml#/IdpGetResponse"
+  tags:
+    - identity_providers
+
+delete:
+  summary: 删除指定的认证源
+  parameters:
+    - $ref: '../parameters/identity_provider.yaml#/idp_id'
+  responses:
+    200:
+      description: 被删除的认证源信息
+      schema:
+        $ref: "../schemas/identity_provider.yaml#/IdpGetResponse"
+  tags:
+    - identity_providers
diff --git a/docs/identity/identity_providers.yaml b/docs/identity/identity_providers.yaml
new file mode 100644
index 0000000000..cfd153f026
--- /dev/null
+++ b/docs/identity/identity_providers.yaml
@@ -0,0 +1,29 @@
+get:
+  summary: 按指定条件列出认证源
+  parameters:
+    - $ref: '../parameters/common.yaml#/offset'
+    - $ref: '../parameters/common.yaml#/limit'
+  responses:
+    200:
+      description: 认证源列表信息
+      schema:
+        $ref: "../schemas/identity_provider.yaml#/IdpListResponse"
+  tags:
+    - identity_providers
+
+post:
+  summary: 创建认证源
+  parameters:
+    - name: identity_provider
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/identity_provider.yaml#/IdpCreateInput"
+  responses:
+    200:
+      description: 认证源信息
+      schema:
+        $ref: "../schemas/identity_provider.yaml#/IdpGetResponse"
+  tags:
+    - identity_providers
+
diff --git a/docs/identity/policies.yaml b/docs/identity/policies.yaml
new file mode 100644
index 0000000000..4e95f29f19
--- /dev/null
+++ b/docs/identity/policies.yaml
@@ -0,0 +1,31 @@
+get:
+  summary: 按指定过滤条件列出权限
+  parameters:
+    - $ref: '../parameters/common.yaml#/offset'
+    - $ref: '../parameters/common.yaml#/limit'
+    - $ref: '../parameters/common.yaml#/scope'
+    - $ref: '../parameters/identity.yaml#/project_domain'
+  responses:
+    200:
+      description: 权限列表信息
+      schema:
+        $ref: "../schemas/policy.yaml#/PolicyListResponse"
+  tags:
+    - policies
+
+post:
+  summary: 新建一个权限
+  parameters:
+    - name: policy
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/policy.yaml#/PolicyCreateInput"
+  responses:
+    200:
+      description: 权限信息
+      schema:
+        $ref: "../schemas/policy.yaml#/PolicyGetResponse"
+  tags:
+    - policies
+
diff --git a/docs/identity/policy.yaml b/docs/identity/policy.yaml
new file mode 100644
index 0000000000..bdc0cfddb5
--- /dev/null
+++ b/docs/identity/policy.yaml
@@ -0,0 +1,40 @@
+get:
+  summary: 获得指定权限的详情
+  parameters:
+    - $ref: '../parameters/policy.yaml#/policy_id'
+  responses:
+    200:
+      description: 权限信息
+      schema:
+        $ref: "../schemas/policy.yaml#/PolicyGetResponse"
+  tags:
+    - policies
+
+patch:
+  summary: 更新指定权限的属性
+  parameters:
+    - $ref: '../parameters/policy.yaml#/policy_id'
+    - name: policy
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/policy.yaml#/PolicyPutRequestInput"
+  responses:
+    200:
+      description: 权限信息
+      schema:
+        $ref: "../schemas/policy.yaml#/PolicyGetResponse"
+  tags:
+    - policies
+
+delete:
+  summary: 删除指定权限
+  parameters:
+    - $ref: '../parameters/policy.yaml#/policy_id'
+  responses:
+    200:
+      description: 被删除的权限信息
+      schema:
+        $ref: "../schemas/policy.yaml#/PolicyGetResponse"
+  tags:
+    - policies
diff --git a/docs/identity/project.yaml b/docs/identity/project.yaml
new file mode 100644
index 0000000000..702e12a54b
--- /dev/null
+++ b/docs/identity/project.yaml
@@ -0,0 +1,40 @@
+get:
+  summary: 获得指定项目的详情
+  parameters:
+    - $ref: '../parameters/project.yaml#/project_id'
+  responses:
+    200:
+      description: 项目信息
+      schema:
+        $ref: "../schemas/project.yaml#/ProjectGetResponse"
+  tags:
+    - projects
+
+put:
+  summary: 更新指定项目的属性
+  parameters:
+    - $ref: '../parameters/project.yaml#/project_id'
+    - name: project
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/project.yaml#/ProjectPutRequestInput"
+  responses:
+    200:
+      description: 项目信息
+      schema:
+        $ref: "../schemas/project.yaml#/ProjectGetResponse"
+  tags:
+    - projects
+
+delete:
+  summary: 删除指定项目
+  parameters:
+    - $ref: '../parameters/project.yaml#/project_id'
+  responses:
+    200:
+      description: 被删除的项目信息
+      schema:
+        $ref: "../schemas/project.yaml#/ProjectGetResponse"
+  tags:
+    - projects
diff --git a/docs/identity/projectgrouprole.yaml b/docs/identity/projectgrouprole.yaml
new file mode 100644
index 0000000000..15ec0bd3b3
--- /dev/null
+++ b/docs/identity/projectgrouprole.yaml
@@ -0,0 +1,23 @@
+put:
+  summary: 将组以指定角色加入项目
+  parameters:
+    - $ref: '../parameters/identity.yaml#/project_id'
+    - $ref: '../parameters/identity.yaml#/group_id'
+    - $ref: '../parameters/identity.yaml#/role_id'
+  responses:
+    200:
+      description: 成功
+  tags:
+    - roles
+
+delete:
+  summary: 将组在项目中的角色删除
+  parameters:
+    - $ref: '../parameters/identity.yaml#/project_id'
+    - $ref: '../parameters/identity.yaml#/group_id'
+    - $ref: '../parameters/identity.yaml#/role_id'
+  responses:
+    200:
+      description: 成功
+  tags:
+    - roles
diff --git a/docs/identity/projects.yaml b/docs/identity/projects.yaml
new file mode 100644
index 0000000000..30cf0ecda4
--- /dev/null
+++ b/docs/identity/projects.yaml
@@ -0,0 +1,31 @@
+get:
+  summary: 按指定条件列出项目
+  parameters:
+    - $ref: '../parameters/common.yaml#/offset'
+    - $ref: '../parameters/common.yaml#/limit'
+    - $ref: '../parameters/common.yaml#/scope'
+    - $ref: '../parameters/identity.yaml#/project_domain'
+  responses:
+    200:
+      description: 项目列表信息
+      schema:
+        $ref: "../schemas/project.yaml#/ProjectListResponse"
+  tags:
+    - projects
+
+post:
+  summary: 新建一个项目
+  parameters:
+    - name: project
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/project.yaml#/ProjectCreateInput"
+  responses:
+    200:
+      description: 项目信息
+      schema:
+        $ref: "../schemas/project.yaml#/ProjectGetResponse"
+  tags:
+    - projects
+
diff --git a/docs/identity/projectuserrole.yaml b/docs/identity/projectuserrole.yaml
new file mode 100644
index 0000000000..ce3deb51ed
--- /dev/null
+++ b/docs/identity/projectuserrole.yaml
@@ -0,0 +1,23 @@
+put:
+  summary: 将用户以指定角色加入项目
+  parameters:
+    - $ref: '../parameters/identity.yaml#/project_id'
+    - $ref: '../parameters/identity.yaml#/user_id'
+    - $ref: '../parameters/identity.yaml#/role_id'
+  responses:
+    200:
+      description: 成功
+  tags:
+    - roles
+
+delete:
+  summary: 将用户在项目中的角色删除
+  parameters:
+    - $ref: '../parameters/identity.yaml#/project_id'
+    - $ref: '../parameters/identity.yaml#/user_id'
+    - $ref: '../parameters/identity.yaml#/role_id'
+  responses:
+    200:
+      description: 成功
+  tags:
+    - roles
diff --git a/docs/identity/region.yaml b/docs/identity/region.yaml
new file mode 100644
index 0000000000..37a8ee5133
--- /dev/null
+++ b/docs/identity/region.yaml
@@ -0,0 +1,40 @@
+get:
+  summary: 获得指定区域的详情
+  parameters:
+    - $ref: '../parameters/region.yaml#/region_id'
+  responses:
+    200:
+      description: 区域信息
+      schema:
+        $ref: "../schemas/region.yaml#/RegionGetResponse"
+  tags:
+    - regions
+
+put:
+  summary: 更新指定区域的属性
+  parameters:
+    - $ref: '../parameters/region.yaml#/region_id'
+    - name: region
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/region.yaml#/RegionPutRequestInput"
+  responses:
+    200:
+      description: 区域信息
+      schema:
+        $ref: "../schemas/region.yaml#/RegionGetResponse"
+  tags:
+    - regions
+
+delete:
+  summary: 删除指定区域
+  parameters:
+    - $ref: '../parameters/region.yaml#/region_id'
+  responses:
+    200:
+      description: 被删除的区域信息
+      schema:
+        $ref: "../schemas/region.yaml#/RegionGetResponse"
+  tags:
+    - regions
diff --git a/docs/identity/regions.yaml b/docs/identity/regions.yaml
new file mode 100644
index 0000000000..9a1ab71878
--- /dev/null
+++ b/docs/identity/regions.yaml
@@ -0,0 +1,28 @@
+get:
+  summary: 按指定条件列出区域
+  parameters:
+    - $ref: '../parameters/common.yaml#/offset'
+    - $ref: '../parameters/common.yaml#/limit'
+  responses:
+    200:
+      description: 区域列表信息
+      schema:
+        $ref: "../schemas/region.yaml#/RegionListResponse"
+  tags:
+    - regions
+
+post:
+  summary: 新建一个区域
+  parameters:
+    - name: region
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/region.yaml#/RegionCreateInput"
+  responses:
+    200:
+      description: 区域信息
+      schema:
+        $ref: "../schemas/region.yaml#/RegionGetResponse"
+  tags:
+    - regions
diff --git a/docs/identity/role.yaml b/docs/identity/role.yaml
new file mode 100644
index 0000000000..bf79b760c7
--- /dev/null
+++ b/docs/identity/role.yaml
@@ -0,0 +1,40 @@
+get:
+  summary: 获得指定角色的详情
+  parameters:
+    - $ref: '../parameters/role.yaml#/role_id'
+  responses:
+    200:
+      description: 角色信息
+      schema:
+        $ref: "../schemas/role.yaml#/RoleGetResponse"
+  tags:
+    - roles
+
+put:
+  summary: 更新指定角色的属性
+  parameters:
+    - $ref: '../parameters/role.yaml#/role_id'
+    - name: role
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/role.yaml#/RolePutRequestInput"
+  responses:
+    200:
+      description: 角色信息
+      schema:
+        $ref: "../schemas/role.yaml#/RoleGetResponse"
+  tags:
+    - roles
+
+delete:
+  summary: 删除指定角色
+  parameters:
+    - $ref: '../parameters/role.yaml#/role_id'
+  responses:
+    200:
+      description: 被删除的角色信息
+      schema:
+        $ref: "../schemas/role.yaml#/RoleGetResponse"
+  tags:
+    - roles
diff --git a/docs/identity/roleassignments.yaml b/docs/identity/roleassignments.yaml
new file mode 100644
index 0000000000..d413479b58
--- /dev/null
+++ b/docs/identity/roleassignments.yaml
@@ -0,0 +1,18 @@
+get:
+  summary: 按指定条件列出用户或者组加入项目的信息
+  parameters:
+    - $ref: '../parameters/roleassignments.yaml#/user.id'
+    - $ref: '../parameters/roleassignments.yaml#/group.id'
+    - $ref: '../parameters/roleassignments.yaml#/role.id'
+    - $ref: '../parameters/roleassignments.yaml#/scope.domain.id'
+    - $ref: '../parameters/roleassignments.yaml#/scope.project.id'
+    - $ref: '../parameters/roleassignments.yaml#/include_names'
+    - $ref: '../parameters/roleassignments.yaml#/effective'
+    - $ref: '../parameters/roleassignments.yaml#/include_system'
+  responses:
+    200:
+      description: 用户或组加入项目的信息列表
+      schema:
+        $ref: "../schemas/roleassignments.yaml#/RolAssignmentListResponse"
+  tags:
+    - role_assignments
diff --git a/docs/identity/roles.yaml b/docs/identity/roles.yaml
new file mode 100644
index 0000000000..d597f0a670
--- /dev/null
+++ b/docs/identity/roles.yaml
@@ -0,0 +1,30 @@
+get:
+  summary: 按指定条件列出角色
+  parameters:
+    - $ref: '../parameters/common.yaml#/offset'
+    - $ref: '../parameters/common.yaml#/limit'
+    - $ref: '../parameters/common.yaml#/scope'
+    - $ref: '../parameters/identity.yaml#/project_domain'
+  responses:
+    200:
+      description: 角色列表信息
+      schema:
+        $ref: "../schemas/role.yaml#/RoleListResponse"
+  tags:
+    - roles
+
+post:
+  summary: 新建一个角色
+  parameters:
+    - name: role
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/role.yaml#/RoleCreateInput"
+  responses:
+    200:
+      description: 角色信息
+      schema:
+        $ref: "../schemas/role.yaml#/RoleGetResponse"
+  tags:
+    - roles
diff --git a/docs/identity/service.yaml b/docs/identity/service.yaml
new file mode 100644
index 0000000000..11c4c35d98
--- /dev/null
+++ b/docs/identity/service.yaml
@@ -0,0 +1,40 @@
+get:
+  summary: 获得指定服务的详情
+  parameters:
+    - $ref: '../parameters/service.yaml#/service_id'
+  responses:
+    200:
+      description: 服务信息
+      schema:
+        $ref: "../schemas/service.yaml#/ServiceGetResponse"
+  tags:
+    - services
+
+put:
+  summary: 更新指定服务的属性
+  parameters:
+    - $ref: '../parameters/service.yaml#/service_id'
+    - name: service
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/service.yaml#/ServicePutRequestInput"
+  responses:
+    200:
+      description: 服务信息
+      schema:
+        $ref: "../schemas/service.yaml#/ServiceGetResponse"
+  tags:
+    - services
+
+delete:
+  summary: 删除指定服务
+  parameters:
+    - $ref: '../parameters/service.yaml#/service_id'
+  responses:
+    200:
+      description: 被删除的服务信息
+      schema:
+        $ref: "../schemas/service.yaml#/ServiceGetResponse"
+  tags:
+    - services
diff --git a/docs/identity/services.yaml b/docs/identity/services.yaml
new file mode 100644
index 0000000000..5594577280
--- /dev/null
+++ b/docs/identity/services.yaml
@@ -0,0 +1,29 @@
+get:
+  summary: 按指定条件列出服务
+  parameters:
+    - $ref: '../parameters/common.yaml#/offset'
+    - $ref: '../parameters/common.yaml#/limit'
+    - $ref: '../parameters/common.yaml#/search'
+  responses:
+    200:
+      description: 服务列表信息
+      schema:
+        $ref: "../schemas/service.yaml#/ServiceListResponse"
+  tags:
+    - services
+
+post:
+  summary: 新建一个服务
+  parameters:
+    - name: service
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/service.yaml#/ServiceCreateInput"
+  responses:
+    200:
+      description: 服务信息
+      schema:
+        $ref: "../schemas/service.yaml#/ServiceGetResponse"
+  tags:
+    - services
diff --git a/docs/identity/user.yaml b/docs/identity/user.yaml
new file mode 100644
index 0000000000..df43e9f572
--- /dev/null
+++ b/docs/identity/user.yaml
@@ -0,0 +1,40 @@
+get:
+  summary: 获得指定用户的详情
+  parameters:
+    - $ref: '../parameters/user.yaml#/user_id'
+  responses:
+    200:
+      description: 用户信息
+      schema:
+        $ref: "../schemas/user.yaml#/UserGetResponse"
+  tags:
+    - users
+
+put:
+  summary: 更新指定用户的信息
+  parameters:
+    - $ref: '../parameters/user.yaml#/user_id'
+    - name: user
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/user.yaml#/UserPutRequestInput"
+  responses:
+    200:
+      description: 用户信息
+      schema:
+        $ref: "../schemas/user.yaml#/UserGetResponse"
+  tags:
+    - users
+
+delete:
+  summary: 删除指定的用户
+  parameters:
+    - $ref: '../parameters/user.yaml#/user_id'
+  responses:
+    200:
+      description: 被删除的用户信息
+      schema:
+        $ref: "../schemas/user.yaml#/UserGetResponse"
+  tags:
+    - users
diff --git a/docs/identity/users.yaml b/docs/identity/users.yaml
new file mode 100644
index 0000000000..0c788e0577
--- /dev/null
+++ b/docs/identity/users.yaml
@@ -0,0 +1,32 @@
+get:
+  summary: 按指定条件列出用户
+  parameters:
+    - $ref: '../parameters/common.yaml#/offset'
+    - $ref: '../parameters/common.yaml#/limit'
+    - $ref: '../parameters/common.yaml#/scope'
+    - $ref: '../parameters/identity.yaml#/project_domain'
+    - $ref: '../parameters/user.yaml#/system'
+  responses:
+    200:
+      description: 用户列表信息
+      schema:
+        $ref: "../schemas/user.yaml#/UserListResponse"
+  tags:
+    - users
+
+post:
+  summary: 新建一个本地用户
+  parameters:
+    - name: user
+      in: body
+      required: true
+      schema:
+        $ref: "../schemas/user.yaml#/UserCreateInput"
+  responses:
+    200:
+      description: 用户信息
+      schema:
+        $ref: "../schemas/user.yaml#/UserGetResponse"
+  tags:
+    - users
+
diff --git a/docs/identity/verify_v2.yaml b/docs/identity/verify_v2.yaml
new file mode 100644
index 0000000000..825f50550c
--- /dev/null
+++ b/docs/identity/verify_v2.yaml
@@ -0,0 +1,11 @@
+get:
+  summary: keystone v2验证token API
+  parameters:
+    - $ref: '../parameters/auth.yaml#/token'
+  responses:
+    200:
+      description: 角色列表信息
+      schema:
+        $ref: "../schemas/auth.yaml#/Auth2Response"
+  tags:
+    - authentication
diff --git a/docs/image/image.yaml b/docs/image/image.yaml
index bf6c899d3d..c70f209fba 100644
--- a/docs/image/image.yaml
+++ b/docs/image/image.yaml
@@ -88,7 +88,7 @@ head:
           #example: 2019-05-30T09:26:41.000000Z
           description: 镜像最近一次更新时间
   tags:
-    - glance
+    - images
 
 put:
   parameters:
@@ -106,7 +106,7 @@ put:
       schema:
         $ref: "../schemas/image.yaml#/ImageResponse"
   tags:
-    - glance
+    - images 
 get:
   parameters:
     - in: query
@@ -116,7 +116,7 @@ get:
       name: torrent
       type: boolean
   tags:
-    - glance
+    - images 
 
   summary: 下载镜像
   responses:
diff --git a/docs/image/images.yaml b/docs/image/images.yaml
index f7a95640d7..1f3bd2ae28 100644
--- a/docs/image/images.yaml
+++ b/docs/image/images.yaml
@@ -15,4 +15,4 @@ get:
       schema:
         $ref: "../schemas/image.yaml#/ImageListResponse"
   tags:
-    - glance
+    - images
diff --git a/docs/index.yaml b/docs/index.yaml
index 2df2893903..5f66fdd5be 100644
--- a/docs/index.yaml
+++ b/docs/index.yaml
@@ -28,10 +28,14 @@ securityDefinitions:
 security:
   - keystone: []
 
-tags:
-  - name: instance
-
 paths:
+  /v2.0/tokens:
+    $ref: "./identity/auth_v2.yaml"
+  /v2.0/tokens/{token}:
+    $ref: "./identity/verify_v2.yaml"
+  /v3/auth/tokens:
+    $ref: "./identity/auth_v3.yaml"
+
   /storages:
     $ref: "./storage/storages.yaml"
   /storages/{storageId}:
@@ -207,3 +211,78 @@ paths:
     $ref: "./loadbalancer/loadbalancerbackends.yaml"
   /loadbalancerbackends/{loadbalancerbackendId}:
     $ref: "./loadbalancer/loadbalancerbackend.yaml"
+
+  /identity_providers:
+    $ref: "./identity/identity_providers.yaml"
+  /identity_providers/{idp_id}:
+    $ref: "./identity/identity_provider.yaml"
+
+  /domains:
+    $ref: "./identity/domains.yaml"
+  /domains/{domain_id}:
+    $ref: "./identity/domain.yaml"
+
+  /users:
+    $ref: "./identity/users.yaml" 
+  /users/{user_id}:
+    $ref: "./identity/user.yaml" 
+
+  /groups:
+    $ref: "./identity/groups.yaml"
+  /groups/{group_id}:
+    $ref: "./identity/group.yaml"
+  /groups/{group_id}/users/{user_id}:
+    $ref: "./identity/groupuser.yaml"
+
+  /projects:
+    $ref: "./identity/projects.yaml"
+  /projects/{project_id}:
+    $ref: "./identity/project.yaml"
+
+  /roles:
+    $ref: "./identity/roles.yaml"
+  /roles/{role_id}:
+    $ref: "./identity/role.yaml"
+  /projects/{project_id}/users/{user_id}/roles/{role_id}:
+    $ref: "./identity/projectuserrole.yaml"
+  /projects/{project_id}/groups/{group_id}/roles/{role_id}:
+    $ref: "./identity/projectgrouprole.yaml"
+
+  /policies:
+    $ref: "./identity/policies.yaml"
+  /policies/{policy_id}:
+    $ref: "./identity/policy.yaml"
+
+  /credentials:
+    $ref: "./identity/credentials.yaml"
+
+  /role_assignments:
+    $ref: "./identity/roleassignments.yaml"
+
+  /regions:
+    $ref: "./identity/regions.yaml"
+  /regions/{region_id}:
+    $ref: "./identity/region.yaml"
+
+  /services:
+    $ref: "./identity/services.yaml"
+  /services/{service_id}:
+    $ref: "./identity/service.yaml"
+
+  /endpoints:
+    $ref: "./identity/endpoints.yaml"
+  /endpoints/{endpoint_id}:
+    $ref: "./identity/endpoint.yaml"
+
+  /quotas:
+    $ref: "./quotas/quotas.yaml"
+  /quotas/{project_id}:
+    $ref: "./quotas/projectquotas.yaml"
+  /quotas/projects/{project_id}:
+    $ref: "./quotas/projectquotas.yaml"
+  /quotas/domains/{domain_id}:
+    $ref: "./quotas/projectquotas.yaml"
+  /quotas/domains:
+    $ref: "./quotas/quotalist.yaml"
+  /quotas/projects:
+    $ref: "./quotas/quotalist.yaml"
diff --git a/docs/parameters/auth.yaml b/docs/parameters/auth.yaml
new file mode 100644
index 0000000000..dfc44e23ca
--- /dev/null
+++ b/docs/parameters/auth.yaml
@@ -0,0 +1,14 @@
+token:
+  name: token
+  type: string
+  in: path
+  required: true
+  description: keystone v2 token to be verified
+
+token3:
+  name: X-Subject-Token
+  in: header
+  schema:
+    type: string
+  required: true
+  description: keystone v3 token to be verified
diff --git a/docs/parameters/common.yaml b/docs/parameters/common.yaml
index 67828aa55b..11530512ef 100644
--- a/docs/parameters/common.yaml
+++ b/docs/parameters/common.yaml
@@ -10,6 +10,23 @@ limit:
   type: integer
   default: 20
   description: 查询限制量
+admin:
+  name: admin
+  in: query
+  type: boolean
+  default: false
+  description: obsolete, equivalent to scope=system
+scope:
+  name: scope
+  in: query
+  type: string
+  default: project
+  description: specify query scope, either project, domain or system
+search:
+  name: search
+  in: query
+  type: string
+  description: 模糊查询, 对结果中任意字符串字段进行包含该字符串的过滤
 billing_type:
   name: billing_type
   in: query
@@ -77,4 +94,16 @@ override_pending_delete:
   name: override_pending_delete
   in: query
   type: boolean
-  description: 从回收站删除资源时需要指定此参数为true, 回收站资源到期会自动释放。到期清理时间由服务参数PendingDeleteExpireSeconds确定。默认是259200秒（3天）
\ No newline at end of file
+  description: 从回收站删除资源时需要指定此参数为true, 回收站资源到期会自动释放。到期清理时间由服务参数PendingDeleteExpireSeconds确定。默认是259200秒（3天）
+
+name:
+  name: name
+  in: body
+  type: string
+  description: 更新资源的名称
+
+description:
+  name: description
+  in: body
+  type: string
+  description: 更新资源的描述
diff --git a/docs/parameters/credential.yaml b/docs/parameters/credential.yaml
new file mode 100644
index 0000000000..daaad498b2
--- /dev/null
+++ b/docs/parameters/credential.yaml
@@ -0,0 +1,13 @@
+type:
+  name: type
+  type: string
+  in: query
+  example: totp
+  description: 以type字段过滤列表结果, 例如totp, recovery_secret
+
+user_id:
+  name: user_id
+  type: string
+  in: query
+  description: 以user_id过滤指定用户的credentials
+
diff --git a/docs/parameters/domain.yaml b/docs/parameters/domain.yaml
new file mode 100644
index 0000000000..14d586e8c9
--- /dev/null
+++ b/docs/parameters/domain.yaml
@@ -0,0 +1,6 @@
+domain_id:
+  name: domain_id
+  type: string
+  required: true
+  in: path
+  description: 域ID
diff --git a/docs/parameters/endpoint.yaml b/docs/parameters/endpoint.yaml
new file mode 100644
index 0000000000..56ad3411f1
--- /dev/null
+++ b/docs/parameters/endpoint.yaml
@@ -0,0 +1,6 @@
+endpoint_id:
+  name: endpoint_id
+  type: string
+  required: true
+  in: path
+  description: 服务接入点ID
diff --git a/docs/parameters/group.yaml b/docs/parameters/group.yaml
new file mode 100644
index 0000000000..05a689c9b0
--- /dev/null
+++ b/docs/parameters/group.yaml
@@ -0,0 +1,6 @@
+group_id:
+  name: group_id
+  type: string
+  required: true
+  in: path
+  description: 组ID
diff --git a/docs/parameters/identity.yaml b/docs/parameters/identity.yaml
new file mode 100644
index 0000000000..a1fad4bd21
--- /dev/null
+++ b/docs/parameters/identity.yaml
@@ -0,0 +1,29 @@
+project_domain:
+  name: project_domain
+  type: string
+  in: query
+  description: 以域的名称或者ID过滤列表结果
+
+project_id:
+  name: project_id
+  type: string
+  in: path
+  description: 项目ID
+
+user_id:
+  name: user_id
+  type: string
+  in: path
+  description: 用户ID
+
+group_id:
+  name: group_id
+  type: string
+  in: path
+  description: 组ID
+
+role_id:
+  name: role_id
+  type: string
+  in: path
+  description: 角色ID
diff --git a/docs/parameters/identity_provider.yaml b/docs/parameters/identity_provider.yaml
new file mode 100644
index 0000000000..4fd2236d1a
--- /dev/null
+++ b/docs/parameters/identity_provider.yaml
@@ -0,0 +1,6 @@
+idp_id:
+  name: idp_id
+  type: string
+  required: true
+  in: path
+  description: 认证源ID
diff --git a/docs/parameters/policy.yaml b/docs/parameters/policy.yaml
new file mode 100644
index 0000000000..1e347102c2
--- /dev/null
+++ b/docs/parameters/policy.yaml
@@ -0,0 +1,6 @@
+policy_id:
+  name: policy_id
+  type: string
+  required: true
+  in: path
+  description: 权限ID或者名称
diff --git a/docs/parameters/project.yaml b/docs/parameters/project.yaml
new file mode 100644
index 0000000000..4198faa9ea
--- /dev/null
+++ b/docs/parameters/project.yaml
@@ -0,0 +1,6 @@
+project_id:
+  name: project_id
+  type: string
+  required: true
+  in: path
+  description: 项目ID
diff --git a/docs/parameters/quota.yaml b/docs/parameters/quota.yaml
new file mode 100644
index 0000000000..a27ef2b3cb
--- /dev/null
+++ b/docs/parameters/quota.yaml
@@ -0,0 +1,20 @@
+scope:
+  name: scope
+  in: query
+  type: string
+  description: 指定所查询的配额的作用范围，可能的值为project|domain。如果为project，则查询当前项目的配额，缺省为project。如果为domain，则查询当前项目的配额。
+
+project_id:
+  name: project_id
+  in: path
+  required: true
+  type: string
+  description: 查询指定项目的配额
+
+domain_id:
+  name: domain_id
+  in: path
+  required: true
+  type: string
+  description: 查询指定域的配额
+
diff --git a/docs/parameters/region.yaml b/docs/parameters/region.yaml
new file mode 100644
index 0000000000..ca95164f9c
--- /dev/null
+++ b/docs/parameters/region.yaml
@@ -0,0 +1,6 @@
+region_id:
+  name: region_id
+  type: string
+  required: true
+  in: path
+  description: 区域ID
diff --git a/docs/parameters/role.yaml b/docs/parameters/role.yaml
new file mode 100644
index 0000000000..91d8da7a62
--- /dev/null
+++ b/docs/parameters/role.yaml
@@ -0,0 +1,6 @@
+role_id:
+  name: role_id
+  type: string
+  required: true
+  in: path
+  description: 角色ID
diff --git a/docs/parameters/roleassignments.yaml b/docs/parameters/roleassignments.yaml
new file mode 100644
index 0000000000..722e374a58
--- /dev/null
+++ b/docs/parameters/roleassignments.yaml
@@ -0,0 +1,47 @@
+user.id:
+  name: user.id
+  type: string
+  in: query
+  description: 只列出指定用户的项目角色信息
+
+group.id:
+  name: group.id
+  type: string
+  in: query
+  description: 只列出指定组的项目角色信息
+
+role.id:
+  name: role.id
+  type: string
+  in: query
+  description: 只列出指定角色的用户和组加入项目的信息
+
+scope.domain.id:
+  name: scope.domain.id
+  type: string
+  in: query
+  description: 只列出指定域下的项目的用户或者组加入项目的信息
+
+scope.project.id:
+  name: scope.poroject.id
+  type: string
+  in: query
+  description: 只列出指定项目的用户或者组加入的信息
+
+include_names:
+  name: include_names
+  type: boolean
+  in: query
+  description: 结果包含用户，组，项目，角色的名称
+
+effective:
+  name: effective
+  type: boolean
+  in: query
+  description: 把组加入项目的信息展开，只显示用户加入项目的信息
+
+include_system:
+  name: include_system
+  type: boolean
+  in: query
+  description: 包含系统用户的角色项目信息
diff --git a/docs/parameters/service.yaml b/docs/parameters/service.yaml
new file mode 100644
index 0000000000..537868fa4e
--- /dev/null
+++ b/docs/parameters/service.yaml
@@ -0,0 +1,6 @@
+service_id:
+  name: service_id
+  type: string
+  required: true
+  in: path
+  description: 服务ID
diff --git a/docs/parameters/user.yaml b/docs/parameters/user.yaml
new file mode 100644
index 0000000000..af05af4e99
--- /dev/null
+++ b/docs/parameters/user.yaml
@@ -0,0 +1,12 @@
+system:
+  name: system
+  type: boolean
+  in: query
+  description: 是否显示系统账号用户，默认为否
+
+user_id:
+  name: user_id
+  type: string
+  required: true
+  in: path
+  description: 用户ID
diff --git a/docs/quotas/domainquotas.yaml b/docs/quotas/domainquotas.yaml
new file mode 100644
index 0000000000..6a78831399
--- /dev/null
+++ b/docs/quotas/domainquotas.yaml
@@ -0,0 +1,11 @@
+get:
+  summary: 获得指定域的配额
+  parameters:
+    $ref: "../parameters/quota.yaml#/domain_id"
+  responses:
+    200:
+      description: 配额信息
+      schema:
+        $ref: "../schemas/quota.yaml#/QuotaGetResponse"
+  tags:
+    - quota
diff --git a/docs/quotas/projectquotas.yaml b/docs/quotas/projectquotas.yaml
new file mode 100644
index 0000000000..756a4f137c
--- /dev/null
+++ b/docs/quotas/projectquotas.yaml
@@ -0,0 +1,11 @@
+get:
+  summary: 获得指定项目的配额
+  parameters:
+    $ref: "../parameters/quota.yaml#/project_id"
+  responses:
+    200:
+      description: 配额信息
+      schema:
+        $ref: "../schemas/quota.yaml#/QuotaGetResponse"
+  tags:
+    - quota
diff --git a/docs/quotas/quotalist.yaml b/docs/quotas/quotalist.yaml
new file mode 100644
index 0000000000..ea4a3c454b
--- /dev/null
+++ b/docs/quotas/quotalist.yaml
@@ -0,0 +1,9 @@
+get:
+  summary: 获取全局所有域的配额信息
+  responses:
+    200:
+      description: 配额信息
+      schema:
+        $ref: "../schemas/quota.yaml#/QuotaGetResponse"
+  tags:
+    - quota
diff --git a/docs/quotas/quotas.yaml b/docs/quotas/quotas.yaml
new file mode 100644
index 0000000000..364b6f5942
--- /dev/null
+++ b/docs/quotas/quotas.yaml
@@ -0,0 +1,11 @@
+get:
+  summary: 获得用户所在项目的配额
+  parameters:
+    - $ref: '../parameters/quota.yaml#/scope'
+  responses:
+    200:
+      description: 配额信息
+      schema:
+        $ref: "../schemas/quota.yaml#/QuotaGetResponse"
+  tags:
+    - quota
diff --git a/docs/schemas/auth.yaml b/docs/schemas/auth.yaml
new file mode 100644
index 0000000000..1fc3718736
--- /dev/null
+++ b/docs/schemas/auth.yaml
@@ -0,0 +1,310 @@
+AuthContext:
+  type: object
+  properties:
+    source:
+      type: string
+      description: 认证来源，可能值为web, api, cli, srv
+    ip:
+      type: string
+      description: 认证发起的IP地址
+
+Auth2Input:
+  type: object
+  properties:
+    password_credentials:
+      type: object
+      description: 采用用户名／密码认证时，用来认证的密码认证信息
+      properties:
+        username:
+          type: string
+          description: 用户名
+        password:
+          type: string
+          description: 密码
+    tenant_name:
+      type: string
+      description: 项目名称
+    tenant_id:
+      type: string
+      description: 项目ID
+    token:
+      type: object
+      description: 采用token认证时，用来认证的token信息
+      properties:
+        id:
+          type: string
+          description: token
+    context:
+      type: object
+      $ref: '#/AuthContext'
+
+Auth2Response:
+  type: object
+  properties:
+    access:
+      type: object
+      $ref: '#/Token2'
+
+Token2:
+  type: object
+  properties:
+    token:
+      type: object
+      description: token信息
+      properties:
+        id:
+          type: string
+          description: token字符串
+        expires:
+          type: string
+          format: date-time
+          description: token到期时间
+        tenant:
+          type: object
+          description: token所属的项目信息
+          $ref: '#/TenantV2'
+    service_catalog:
+      type: array
+      description: 服务目录
+      items:
+        $ref: '#/ServiceV2'
+    user:
+      type: object
+      description: token关联的用户信息
+      properties:
+        id:
+          type: string
+          description: 用户ID
+        name:
+          type: string
+          description: 用户名称
+        username:
+          type: string
+          description: 用户的显示名称
+        roles:
+          type: array
+          items:
+            type: object
+            description: 用户角色
+            properties:
+              name:
+                type: string
+                description: 用户角色名称
+    metadata:
+      type: object
+      properties:
+        is_admin:
+          type: integer
+          description: 是否为管理员
+        roles:
+          type: array
+          description: 角色名称列表
+          items:
+            type: string
+            description: 角色名称
+    context:
+      type: object
+      $ref: '#/AuthContext'
+
+TenantV2:
+  type: object
+  description: keystone v2项目信息
+  properties:
+    id:
+      type: string
+      description: 项目ID
+    name:
+      type: string
+      description: 项目名称
+    enabled:
+      type: boolean
+      description: 项目是否启用
+    description:
+      type: string
+      description: 项目描述
+    domain:
+      type: object
+      $ref: "./roleassignments.yaml#/Domain"
+
+ServiceV2:
+  type: object
+  description: keystone v2服务信息
+  properties:
+    name:
+      type: string
+      description: 服务名称
+    type:
+      type: string
+      description: 服务类型
+    endpoints:
+      type: array
+      description: 接入点列表
+      items:
+        type: object
+        $ref: '#/EndpointV2'
+
+EndpointV2:
+  type: object
+  description: keystone v2接入点信息
+  properties:
+    id:
+      type: string
+      description: 接入点ID
+    region:
+      type: string
+      description: 区域ID
+    internal_url:
+      type: string
+      description: internal url
+    public_url:
+      type: string
+      description: public url
+    admin_url:
+      type: string
+      description: admin url
+
+Auth3Input:
+  type: object
+  description: keystone v3认证请求
+  properties:
+    identity:
+      type: object
+      description: 认证信息
+      $ref: '#/AuthIdentity3'
+    scope:
+      type: object
+      description: 认证scope
+      $ref: './roleassignments.yaml#/Scope'
+    context:
+      type: object
+      $ref: '#/AuthContext'
+
+AuthIdentity3:
+  type: object
+  description: keystone v3认证鉴权信息
+  properties:
+    methods:
+      type: array
+      description: 认证方式列表
+      items:
+        type: string
+        description: 认证方式, 可能值为password, token
+    password:
+      type: object
+      description: 密码认证信息
+      properties:
+        id:
+          type: string
+          description: 用户ID
+        name:
+          type: string
+          description: 用户名称
+        password:
+          type: string
+          description: 密码
+        domain:
+          type: object
+          $ref: "./roleassignments.yaml#/Domain"
+    token: 
+      type: object
+      description: token认证信息
+      properties:
+        id:
+          type: string
+          description: tokenID
+
+Auth3Response:
+  type: object
+  description: keystone v3认证响应
+  properties:
+    token:
+      type: object
+      $ref: '#/TokenV3'
+
+TokenV3:
+  type: object
+  description: keystone v3 token
+  properties:
+    audit_ids:
+      type: array
+      items:
+        type: string
+        description: AuditIds
+    expires_at:
+      type: string
+      format: date-time
+      description: token过期时间
+    is_domain:
+      type: boolean
+      description: 是否为domain的token
+    issued_at:
+      type: string
+      format: date-time
+      description: token发放时间
+    methods:
+      type: array
+      items:
+        type: string
+        description: 请求的methods
+    project:
+      type: object
+      $ref: './roleassignments.yaml#/DomainObject'
+    roles:
+      type: array
+      items:
+        type: object
+        $ref: './roleassignments.yaml#/DomainObject'
+    user:
+      type: object
+      $ref: './roleassignments.yaml#/DomainObject'
+    catalog:
+      type: array
+      items:
+        type: object
+        $ref: '#/ServiceV3'
+    context:
+      type: object
+      $ref: '#/AuthContext'
+
+ServiceV3:
+  type: object
+  decription: keystone V3 service
+  properties:
+    id:
+      type: string
+      description: 服务ID
+    name:
+      type: string
+      description: 服务名称
+    type:
+      type: string
+      description: 服务类型
+    endpoints:
+      type: array
+      description: keystone V3 endpoint
+      items:
+        type: object
+        $ref: '#/EndpointV3'
+
+EndpointV3:
+  type: object
+  description: keystone V3 endpoint
+  properties:
+    id:
+      type: string
+      description: endpoint ID
+    interface:
+      type: string
+      description: endpoint类型, 可能值为：internal, public, admin, console
+    region:
+      type: string
+      description: endpoint所在区域名称
+    region_id:
+      type: string
+      description: endpoint所在区域ID
+    url:
+      type: string
+      description: endpoint URL
+    name:
+      type: string
+      description: endpoint name
diff --git a/docs/schemas/credential.yaml b/docs/schemas/credential.yaml
new file mode 100644
index 0000000000..7a69d7a204
--- /dev/null
+++ b/docs/schemas/credential.yaml
@@ -0,0 +1,50 @@
+CredentialListResponse:
+  type: object
+  properties:
+    limit:
+      type: integer
+      example: 20
+    offset:
+      type: integer
+      example: 0
+    total:
+      type: integer
+      description: 总量
+    credentials:
+      type: array
+      items:
+        $ref: "#/Credential"
+
+CredentialGetResponse:
+  type: object
+  properties:
+    credential:
+      type: object
+      $ref: "#/Credential"
+
+Credential:
+  type: object
+  description: 用户Credentials
+  properties:
+    id:
+      type: string
+      description: 用户CredentialID
+      readOnly: true
+    name:
+      type: string
+      description: 用户Credential名称，域内唯一
+    type:
+      type: string
+      description: 用户Credential类型，totp或者recovery_secret
+    can_delete:
+      type: boolean
+      description: 是否可以删除
+    blob:
+      type: string
+      description: 用户Credential内容，json字符串
+    user_id:
+      type: string
+      description: Credential的所属用户
+    project_id:
+      type: string
+      description: Credential的所属项目
diff --git a/docs/schemas/domain.yaml b/docs/schemas/domain.yaml
new file mode 100644
index 0000000000..a7a5c044d7
--- /dev/null
+++ b/docs/schemas/domain.yaml
@@ -0,0 +1,71 @@
+DomainListResponse:
+  type: object
+  properties:
+    limit:
+      type: integer
+      example: 20
+    offset:
+      type: integer
+      example: 0
+    total:
+      type: integer
+      description: 总量
+    domains:
+      type: array
+      items:
+        $ref: "#/Domain"
+
+DomainGetResponse:
+  type: object
+  properties:
+    domain:
+      type: object
+      $ref: "#/Domain"
+
+DomainPutRequestInput:
+  type: object
+  properties:
+    name:
+      type: string
+      description: 域的名称
+    description:  
+      type: string
+      description: 域的描述
+
+DomainCreateInput:
+  type: object
+  properties:
+    name:
+      type: string
+      required: true
+      description: 域的名称
+    description:
+      type: string
+      description: 域的描述
+
+Domain:
+  type: object
+  description: 域
+  properties:
+    id:
+      type: string
+      description: 域ID
+      readOnly: true
+    name:
+      type: string
+      description: 域名称
+    can_delete:
+      type: boolean
+      description: 是否可以删除
+    idp_id:
+      type: string
+      description: 如果该域为从认证源导入，则idp_id为该认证源的ID
+    idp:
+      type: string
+      description: 如果该域为从认证源导入，则idp为该认证源的name
+    idp_driver:
+      type: string
+      description: 如果该域为从认证源导入，则idp_driver为该认证源的driver
+    idp_entity_id:
+      type: string
+      description: 如果该域为从认证源导入，则idp_entity_id为该域对应资源的原始ID
diff --git a/docs/schemas/endpoint.yaml b/docs/schemas/endpoint.yaml
new file mode 100644
index 0000000000..16daaed46b
--- /dev/null
+++ b/docs/schemas/endpoint.yaml
@@ -0,0 +1,111 @@
+EndpointListResponse:
+  type: object
+  properties:
+    limit:
+      type: integer
+      example: 20
+    offset:
+      type: integer
+      example: 0
+    total:
+      type: integer
+      description: 总量
+    endpoints:
+      type: array
+      items:
+        $ref: "#/Endpoint"
+
+EndpointGetResponse:
+  type: object
+  properties:
+    endpoint:
+      type: object
+      $ref: "#/Endpoint"
+
+EndpointPutRequestInput:
+  type: object
+  properties:
+    name:
+      type: string
+      description: 接入点的名称
+    url:
+      type: string
+      description: 接入点的URL
+    description:  
+      type: string
+      description: 接入点的描述
+    enabled:
+      type: boolean
+      description: 是否启用／禁用接入点
+
+EndpointCreateInput:
+  type: object
+  properties:
+    name:
+      type: string
+      description: 接入点的名称，全局唯一
+      example: keystone
+    url:
+      type: string
+      description: 接入点的URL
+      required: true
+    enabled:
+      type: boolean
+      description: 接入点是否启用／禁用
+      default: true
+    description:
+      type: string
+      description: 接入点的描述
+    service_id:
+      type: string
+      description: 接入点所属的服务ID
+      required: true
+    region_id:
+      type: string
+      description: 接入点所属的区域ID
+      required: true
+      example: Beijing
+    interface:
+      type: string
+      description: 接入点的接口类型，可能值为：internal, public, admin, console
+      example: internal, public, admin, console
+      required: true
+
+Endpoint:
+  type: object
+  description: 接入点
+  properties:
+    id:
+      type: string
+      description: 接入点ID
+      readOnly: true
+    name:
+      type: string
+      description: 接入点名称，全局唯一
+    service_type:
+      type: string
+      description: 接入点所属服务的类型
+    service_name:
+      type: string
+      description: 接入点所属服务的名称
+    service_id:
+      type: string
+      description: 接入点所属服务的ID
+    region_id: 
+      type: string
+      description: 接入点所在区域的ID
+    interface:
+      type: string
+      description: 接入点的接口类型
+    url:
+      type: string
+      description: 接入点的URL
+    enabled:
+      type: boolean
+      description: 接入点是否启用／禁用
+    can_delete:
+      type: boolean
+      description: 是否可以删除
+    description:
+      type: string
+      description: 接入点的描述信息
diff --git a/docs/schemas/group.yaml b/docs/schemas/group.yaml
new file mode 100644
index 0000000000..6e20327d1d
--- /dev/null
+++ b/docs/schemas/group.yaml
@@ -0,0 +1,71 @@
+GroupListResponse:
+  type: object
+  properties:
+    limit:
+      type: integer
+      example: 20
+    offset:
+      type: integer
+      example: 0
+    total:
+      type: integer
+      description: 总量
+    groups:
+      type: array
+      items:
+        $ref: "#/Group"
+
+GroupGetResponse:
+  type: object
+  properties:
+    group:
+      type: object
+      $ref: "#/Group"
+
+GroupPutRequestInput:
+  type: object
+  properties:
+    name:
+      type: string
+      description: 组的名称
+    description:  
+      type: string
+      description: 组的描述
+
+GroupCreateInput:
+  type: object
+  properties:
+    name:
+      type: string
+      required: true
+      description: 组的名称
+    description:
+      type: string
+      description: 组的描述
+
+Group:
+  type: object
+  description: 组
+  properties:
+    id:
+      type: string
+      description: 组ID
+      readOnly: true
+    name:
+      type: string
+      description: 组名，域内唯一
+    can_delete:
+      type: boolean
+      description: 是否可以删除
+    idp_id:
+      type: string
+      description: 如果该组为从认证源导入，则idp_id为该认证源的ID
+    idp:
+      type: string
+      description: 如果该组为从认证源导入，则idp为该认证源的name
+    idp_driver:
+      type: string
+      description: 如果该组为从认证源导入，则idp_driver为该认证源的driver
+    idp_entity_id:
+      type: string
+      description: 如果该组为从认证源导入，则idp_entity_id为该域对应资源的原始ID
diff --git a/docs/schemas/identity_provider.yaml b/docs/schemas/identity_provider.yaml
new file mode 100644
index 0000000000..41cb000f1f
--- /dev/null
+++ b/docs/schemas/identity_provider.yaml
@@ -0,0 +1,69 @@
+IdpListResponse:
+  type: object
+  properties:
+    limit:
+      type: integer
+      example: 20
+    offset:
+      type: integer
+      example: 0
+    total:
+      type: integer
+      description: 总量
+    identity_providers:
+      type: array
+      items:
+        $ref: "#/Idp"
+
+IdpGetResponse:
+  type: object
+  properties:
+    identity_provider:
+      type: object
+      $ref: "#/Idp"
+
+IdpPutRequestInput:
+  type: object
+  properties:
+    name:
+      type: string
+      description: 认证源的名称
+    description:  
+      type: string
+      description: 认证源的描述
+
+IdpCreateInput:
+  type: object
+  properties:
+    name:
+      type: string
+      required: true
+      description: 认证源的名称
+    driver:
+      type: string
+      required: true
+      description: 认证源的driver
+    description:
+      type: string
+      description: 认证源的描述
+
+Idp:
+  type: object
+  description: 认证源
+  properties:
+    id:
+      type: string
+      description: 认证源ID
+      readOnly: true
+    name:
+      type: string
+      description: 认证源名称
+    can_delete:
+      type: boolean
+      description: 是否可以删除
+    driver:
+      type: string
+      description: 认证源类型，目前支持sql, ldap两种
+    template:
+      type: string
+      description: 认证源配置模板，跟driver相关。当driver为ldap时，支持三种模板：msad_one_domain,openldap_one_domain,msad_multi_domain
diff --git a/docs/schemas/policy.yaml b/docs/schemas/policy.yaml
new file mode 100644
index 0000000000..fbfb5fdec0
--- /dev/null
+++ b/docs/schemas/policy.yaml
@@ -0,0 +1,89 @@
+PolicyListResponse:
+  type: object
+  properties:
+    limit:
+      type: integer
+      example: 20
+    offset:
+      type: integer
+      example: 0
+    total:
+      type: integer
+      description: 总量
+    policies:
+      type: array
+      items:
+        $ref: "#/Policy"
+
+PolicyGetResponse:
+  type: object
+  properties:
+    policy:
+      type: object
+      $ref: "#/Policy"
+
+PolicyPutRequestInput:
+  type: object
+  properties:
+    type:
+      type: string
+      description: 权限的名称/类型
+    enabled:
+      type: boolean
+      description: 启用/禁用权限
+    policy:
+      type: string
+      description: 权限的json定义
+    description:  
+      type: string
+      description: 权限的描述
+
+PolicyCreateInput:
+  type: object
+  properties:
+    type:
+      type: string
+      required: true
+      description: 权限的名称/类型
+    enabled:
+      type: boolean
+      description: 启用/禁用权限
+    policy:
+      type: string
+      description: 权限的json定义
+    domain:
+      type: string
+      description: 权限所属的域
+    description:
+      type: string
+      description: 项目的描述
+
+Policy:
+  type: object
+  description: 权限
+  properties:
+    id:
+      type: string
+      description: 权限ID
+      readOnly: true
+    type:
+      type: string
+      description: 权限名称/类型，全局唯一
+    can_delete:
+      type: boolean
+      description: 是否可以删除
+    domain_id:
+      type: string
+      descrption: 所属域ID
+    project_domain:
+      type: string
+      description: 所属域名称
+    enabled:
+      type: boolean
+      description: 是否启用／禁用
+    is_public:
+      type: boolean
+      description: 是否共享
+    policy:
+      type: string
+      description: 权限内容的json定义
diff --git a/docs/schemas/project.yaml b/docs/schemas/project.yaml
new file mode 100644
index 0000000000..1438a0b4ed
--- /dev/null
+++ b/docs/schemas/project.yaml
@@ -0,0 +1,59 @@
+ProjectListResponse:
+  type: object
+  properties:
+    limit:
+      type: integer
+      example: 20
+    offset:
+      type: integer
+      example: 0
+    total:
+      type: integer
+      description: 总量
+    projects:
+      type: array
+      items:
+        $ref: "#/Project"
+
+ProjectGetResponse:
+  type: object
+  properties:
+    project:
+      type: object
+      $ref: "#/Project"
+
+ProjectPutRequestInput:
+  type: object
+  properties:
+    name:
+      type: string
+      description: 项目的名称
+    description:  
+      type: string
+      description: 项目的描述
+
+ProjectCreateInput:
+  type: object
+  properties:
+    name:
+      type: string
+      required: true
+      description: 项目的名称
+    description:
+      type: string
+      description: 项目的描述
+
+Project:
+  type: object
+  description: 项目
+  properties:
+    id:
+      type: string
+      description: 项目ID
+      readOnly: true
+    name:
+      type: string
+      description: 项目名，全局唯一
+    can_delete:
+      type: boolean
+      description: 是否可以删除
diff --git a/docs/schemas/quota.yaml b/docs/schemas/quota.yaml
new file mode 100644
index 0000000000..8966367950
--- /dev/null
+++ b/docs/schemas/quota.yaml
@@ -0,0 +1,29 @@
+QuotaGetResponse:
+  type: object
+  properties:
+    quotas:
+      type: object
+      $ref: '#/Quota'
+
+Quota:
+  type: object
+  description: 配额信息
+  properties:
+    cpu:
+      type: integer
+      description: CPU配额
+    memory:
+      type: integer
+      description: 内存配额
+    usage.cpu:
+      type: integer
+      description: CPU使用量
+    usage.memory:
+      type: integer
+      description: 内存使用量
+    total.cpu:
+      type: integer
+      description: 该字段只有域配额才有，代表该域分配给下属项目的CPU配额的总和
+    total.memory:
+      type: integer
+      description: 该字段只有域配额才有，代表该域分配给下属项目的内存配额的总和
diff --git a/docs/schemas/region.yaml b/docs/schemas/region.yaml
new file mode 100644
index 0000000000..28277b7d26
--- /dev/null
+++ b/docs/schemas/region.yaml
@@ -0,0 +1,67 @@
+RegionListResponse:
+  type: object
+  properties:
+    limit:
+      type: integer
+      example: 20
+    offset:
+      type: integer
+      example: 0
+    total:
+      type: integer
+      description: 总量
+    regions:
+      type: array
+      items:
+        $ref: "#/Region"
+
+RegionGetResponse:
+  type: object
+  properties:
+    region:
+      type: object
+      $ref: "#/Region"
+
+RegionPutRequestInput:
+  type: object
+  properties:
+    name:
+      type: string
+      description: 区域的名称
+    description:  
+      type: string
+      description: 区域的描述
+
+RegionCreateInput:
+  type: object
+  properties:
+    id:
+      type: string
+      required: true
+      description: 区域的ID，全局唯一
+      example: Beijing, Tianjin
+    name:
+      type: string
+      description: 区域的名称，默认和ID一样，也可以不一样
+      example: 北京
+    description:
+      type: string
+      description: 区域的描述
+
+Region:
+  type: object
+  description: 区域
+  properties:
+    id:
+      type: string
+      description: 区域ID
+      readOnly: true
+    name:
+      type: string
+      description: 区域名，全局唯一
+    can_delete:
+      type: boolean
+      description: 是否可以删除
+    description:
+      type: string
+      description: 区域的描述信息
diff --git a/docs/schemas/role.yaml b/docs/schemas/role.yaml
new file mode 100644
index 0000000000..899f45389a
--- /dev/null
+++ b/docs/schemas/role.yaml
@@ -0,0 +1,62 @@
+RoleListResponse:
+  type: object
+  properties:
+    limit:
+      type: integer
+      example: 20
+    offset:
+      type: integer
+      example: 0
+    total:
+      type: integer
+      description: 总量
+    roles:
+      type: array
+      items:
+        $ref: "#/Role"
+
+RoleGetResponse:
+  type: object
+  properties:
+    role:
+      type: object
+      $ref: "#/Role"
+
+RolePutRequestInput:
+  type: object
+  properties:
+    description:  
+      type: string
+      description: 角色的描述
+
+RoleCreateInput:
+  type: object
+  properties:
+    name:
+      type: string
+      required: true
+      description: 角色的名称，全局唯一
+    description:
+      type: string
+      description: 角色的描述
+    is_public:
+      type: boolean
+      description: 角色是否共享
+
+Role:
+  type: object
+  description: 角色
+  properties:
+    id:
+      type: string
+      description: 角色ID
+      readOnly: true
+    name:
+      type: string
+      description: 角色名，全局唯一
+    can_delete:
+      type: boolean
+      description: 是否可以删除
+    is_public:
+      type: boolean
+      description: 是否共享的角色
diff --git a/docs/schemas/roleassignments.yaml b/docs/schemas/roleassignments.yaml
new file mode 100644
index 0000000000..da3426afb2
--- /dev/null
+++ b/docs/schemas/roleassignments.yaml
@@ -0,0 +1,76 @@
+RolAssignmentListResponse:
+  type: object
+  properties:
+    limit:
+      type: integer
+      example: 20
+    offset:
+      type: integer
+      example: 0
+    total:
+      type: integer
+      description: 总量
+    role_assignments:
+      type: array
+      items:
+        $ref: "#/RoleAssignment"
+
+RoleAssignment:
+  type: object
+  description: RoleAssignment
+  properties:
+    scope:
+      type: object
+      description: 角色分配的范围
+      $ref: '#/Scope'
+    user:
+      type: object
+      description: 角色分配的用户
+      $ref: '#/DomainObject'
+    group:
+      type: object
+      description: 角色分配的组
+      $ref: '#/DomainObject'
+    role:
+      type: object
+      description: 角色
+      $ref: '#/DomainObject'
+
+Scope:
+  type: object
+  description: 角色分配的范围
+  properties:
+    project:
+      type: object
+      description: 角色分配关联的项目
+      $ref: '#/DomainObject'
+    domain:
+      type: object
+      description: 角色分配的域
+      $ref: '#/Domain'
+
+DomainObject:
+  type: object
+  description: 域下的资源，可能为用户，组，项目
+  properties:
+    id:
+      type: string
+      description: 资源ID
+    name:
+      type: string
+      description: 资源名称
+    domain:
+      type: object
+      description: 资源归属的域信息
+      $ref: '#/Domain'
+
+Domain:
+  type: object
+  description: 域的信息
+  properties:
+    id:
+      type: string
+      description: 域ID
+    name:
+      type: string
+      description: 域名称
diff --git a/docs/schemas/service.yaml b/docs/schemas/service.yaml
new file mode 100644
index 0000000000..54d7803fa2
--- /dev/null
+++ b/docs/schemas/service.yaml
@@ -0,0 +1,84 @@
+ServiceListResponse:
+  type: object
+  properties:
+    limit:
+      type: integer
+      example: 20
+    offset:
+      type: integer
+      example: 0
+    total:
+      type: integer
+      description: 总量
+    services:
+      type: array
+      items:
+        $ref: "#/Service"
+
+ServiceGetResponse:
+  type: object
+  properties:
+    service:
+      type: object
+      $ref: "#/Service"
+
+ServicePutRequestInput:
+  type: object
+  properties:
+    name:
+      type: string
+      description: 服务的名称
+      example: keystone, region, glance, ...
+    type:
+      type: string
+      description: 服务的类型
+      example: identity, compute, image, ...
+    description:  
+      type: string
+      description: 服务的描述
+    enabled:
+      type: boolean
+      description: 是否启用／禁用服务
+
+ServiceCreateInput:
+  type: object
+  properties:
+    name:
+      type: string
+      description: 服务的名称，全局唯一
+      example: keystone
+    type:
+      type: string
+      description: 服务的类型
+      example: identity
+    enabled:
+      type: boolean
+      description: 服务是否启用／禁用
+      default: true
+    description:
+      type: string
+      description: 服务的描述
+
+Service:
+  type: object
+  description: 服务
+  properties:
+    id:
+      type: string
+      description: 服务ID
+      readOnly: true
+    name:
+      type: string
+      description: 服务名，全局唯一
+    type:
+      type: string
+      description: 服务类型
+    enabled:
+      type: boolean
+      description: 服务是否启用／禁用
+    can_delete:
+      type: boolean
+      description: 是否可以删除
+    description:
+      type: string
+      description: 服务的描述信息
diff --git a/docs/schemas/user.yaml b/docs/schemas/user.yaml
new file mode 100644
index 0000000000..892b81bcd4
--- /dev/null
+++ b/docs/schemas/user.yaml
@@ -0,0 +1,74 @@
+UserListResponse:
+  type: object
+  properties:
+    limit:
+      type: integer
+      example: 20
+    offset:
+      type: integer
+      example: 0
+    total:
+      type: integer
+      description: 总量
+    users:
+      type: array
+      items:
+        $ref: "#/User"
+
+UserGetResponse:
+  type: object
+  properties:
+    user:
+      type: object
+      $ref: "#/User"
+
+UserPutRequestInput:
+  type: object
+  properties:
+    name:
+      type: string
+      description: 用户的名称
+    description:  
+      type: string
+      description: 用户的描述
+
+UserCreateInput:
+  type: object
+  properties:
+    name:
+      type: string
+      required: true
+      description: 用户的名称
+    password:
+      type: string
+      description: 本地用户的密码
+    description:
+      type: string
+      description: 用户的描述
+
+User:
+  type: object
+  description: 用户
+  properties:
+    id:
+      type: string
+      description: 用户ID
+      readOnly: true
+    name:
+      type: string
+      description: 用户名，域内唯一
+    can_delete:
+      type: boolean
+      description: 是否可以删除
+    idp_id:
+      type: string
+      description: 如果该用户为从认证源导入，则idp_id为该认证源的ID
+    idp:
+      type: string
+      description: 如果该用户为从认证源导入，则idp为该认证源的name
+    idp_driver:
+      type: string
+      description: 如果该用户为从认证源导入，则idp_driver为该认证源的driver
+    idp_entity_id:
+      type: string
+      description: 如果该用户为从认证源导入，则idp_entity_id为该域对应资源的原始ID
diff --git a/docs/server.py b/docs/server.py
new file mode 100644
index 0000000000..1dfe9e5cfa
--- /dev/null
+++ b/docs/server.py
@@ -0,0 +1,12 @@
+#!/usr/bin/env python
+
+from SimpleHTTPServer import SimpleHTTPRequestHandler
+import BaseHTTPServer
+
+class CORSRequestHandler (SimpleHTTPRequestHandler):
+    def end_headers (self):
+        self.send_header('Access-Control-Allow-Origin', '*')
+        SimpleHTTPRequestHandler.end_headers(self)
+
+if __name__ == '__main__':
+    BaseHTTPServer.test(CORSRequestHandler, BaseHTTPServer.HTTPServer)