This is an automated email from the ASF dual-hosted git repository.
tianxiaoliang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/servicecomb-kie.git
The following commit(s) were added to refs/heads/master by this push:
new 9ff846d update api doc (#119)
9ff846d is described below
commit 9ff846d44a8ba7b55b4091e7d283404f088f5b46
Author: zhulijian <[email protected]>
AuthorDate: Mon Mar 23 11:02:32 2020 +0800
update api doc (#119)
---
docs/api.yaml | 212 ++++++++++++++++++++++++++++++--------
server/resource/v1/doc_struct.go | 13 ++-
server/resource/v1/kv_resource.go | 2 +-
3 files changed, 181 insertions(+), 46 deletions(-)
diff --git a/docs/api.yaml b/docs/api.yaml
index 2f97638..753dba6 100644
--- a/docs/api.yaml
+++ b/docs/api.yaml
@@ -1,10 +1,10 @@
-swagger: '2.0'
+swagger: "2.0"
info:
- title: ''
- version: ''
+ title: ""
+ version: ""
basePath: /
paths:
- '/v1/{project}/kie/kv':
+ /v1/{project}/kie/kv:
get:
summary: list key values by labels and key
operationId: List
@@ -15,25 +15,32 @@ paths:
type: string
- name: label
in: query
- description: 'label pairs,for example
&label=service:order&label=version:1.0.0'
+ description: label pairs,for example
&label=service:order&label=version:1.0.0
type: string
- name: wait
in: query
- description: 'wait until any kv changed. for example wait=5s, server
will not response until 5 seconds during that time window, if any kv changed,
server will return 200 and kv list, otherwise return 304 and empty body'
+ description: wait until any kv changed. for example wait=5s, server
will not
+ response until 5 seconds during that time window, if any kv
changed, server
+ will return 200 and kv list, otherwise return 304 and empty body
type: string
- name: match
in: query
- description: 'match works with label query param, it specifies label
match pattern. if it is empty, server will return kv which''s labels partial
match the label query param. uf it is exact, server will return kv which''s
labels exact match the label query param'
+ description: match works with label query param, it specifies label
match
+ pattern. if it is empty, server will return kv which's labels
partial match
+ the label query param. uf it is exact, server will return kv
which's labels
+ exact match the label query param
type: string
- name: revision
in: query
- description: 'each time you query,server will return a number in
header X-Kie-Revision. you can record it in client side, use this number as
param value. if current revision is greater than it, server will return data'
+ description: each time you query,server will return a number in
header X-Kie-Revision.
+ you can record it in client side, use this number as param value.
if current
+ revision is greater than it, server will return data
type: string
- - name: offset
+ - name: limit
in: query
description: pagination
type: string
- - name: limit
+ - name: offset
in: query
description: pagination
type: string
@@ -43,21 +50,23 @@ paths:
- application/json
- text/yaml
responses:
- '200':
- description: ''
+ "200":
+ description: ""
schema:
- $ref: '#/definitions/v1.DocResponseGetKey'
+ $ref: '#/definitions/DocResponseGetKey'
headers:
X-Kie-Revision:
- description: 'cluster latest revision number, if key value is
changed, it will increase.'
+ description: cluster latest revision number, if key value is
changed,
+ it will increase.
type: integer
- '304':
+ "304":
description: empty body
- '404':
- description: ''
+ "404":
+ description: ""
headers:
X-Kie-Revision:
- description: 'cluster latest revision number, if key value is
changed, it will increase.'
+ description: cluster latest revision number, if key value is
changed,
+ it will increase.
type: integer
delete:
summary: delete key by kv ID.
@@ -76,11 +85,11 @@ paths:
produces:
- '*/*'
responses:
- '204':
+ "204":
description: Delete success
- '500':
+ "500":
description: Server error
- '/v1/{project}/kie/kv/{key}':
+ /v1/{project}/kie/kv/{key}:
get:
summary: get key values by key and labels
operationId: GetByKey
@@ -95,25 +104,32 @@ paths:
type: string
- name: label
in: query
- description: 'label pairs,for example
&label=service:order&label=version:1.0.0'
+ description: label pairs,for example
&label=service:order&label=version:1.0.0
type: string
- name: wait
in: query
- description: 'wait until any kv changed. for example wait=5s, server
will not response until 5 seconds during that time window, if any kv changed,
server will return 200 and kv list, otherwise return 304 and empty body'
+ description: wait until any kv changed. for example wait=5s, server
will not
+ response until 5 seconds during that time window, if any kv
changed, server
+ will return 200 and kv list, otherwise return 304 and empty body
type: string
- name: match
in: query
- description: 'match works with label query param, it specifies label
match pattern. if it is empty, server will return kv which''s labels partial
match the label query param. uf it is exact, server will return kv which''s
labels exact match the label query param'
+ description: match works with label query param, it specifies label
match
+ pattern. if it is empty, server will return kv which's labels
partial match
+ the label query param. uf it is exact, server will return kv
which's labels
+ exact match the label query param
type: string
- name: revision
in: query
- description: 'each time you query,server will return a number in
header X-Kie-Revision. you can record it in client side, use this number as
param value. if current revision is greater than it, server will return data'
+ description: each time you query,server will return a number in
header X-Kie-Revision.
+ you can record it in client side, use this number as param value.
if current
+ revision is greater than it, server will return data
type: string
- - name: offset
+ - name: limit
in: query
description: pagination
type: string
- - name: limit
+ - name: offset
in: query
description: pagination
type: string
@@ -123,21 +139,23 @@ paths:
- application/json
- text/yaml
responses:
- '200':
+ "200":
description: get key value success
schema:
- $ref: '#/definitions/v1.DocResponseGetKey'
+ $ref: '#/definitions/DocResponseGetKey'
headers:
X-Kie-Revision:
- description: 'cluster latest revision number, if key value is
changed, it will increase.'
+ description: cluster latest revision number, if key value is
changed,
+ it will increase.
type: integer
- '304':
+ "304":
description: empty body
- '404':
- description: ''
+ "404":
+ description: ""
headers:
X-Kie-Revision:
- description: 'cluster latest revision number, if key value is
changed, it will increase.'
+ description: cluster latest revision number, if key value is
changed,
+ it will increase.
type: integer
put:
summary: create or update key value
@@ -151,6 +169,11 @@ paths:
in: path
required: true
type: string
+ - name: Content-Type
+ in: header
+ required: true
+ description: used to indicate the media type of the resource, the
value can be application/json or text/yaml
+ type: string
- name: body
in: body
required: true
@@ -163,11 +186,11 @@ paths:
- application/json
- text/yaml
responses:
- '200':
- description: ''
+ "200":
+ description: ""
schema:
- $ref: '#/definitions/v1.DocResponseSingleKey'
- '/v1/{project}/kie/revision/{key_id}':
+ $ref: '#/definitions/DocResponseSingleKey'
+ /v1/{project}/kie/revision/{key_id}:
get:
summary: get all revisions by key id
operationId: GetRevisions
@@ -187,24 +210,87 @@ paths:
- application/json
- text/yaml
responses:
- '200':
- description: ''
+ "200":
+ description: ""
schema:
type: array
items:
- $ref: '#/definitions/v1.DocResponseSingleKey'
+ $ref: '#/definitions/DocResponseSingleKey'
+ /v1/{project}/kie/track:
+ get:
+ summary: get polling tracks of clients of kie server
+ operationId: GetPollingData
+ parameters:
+ - name: project
+ in: path
+ required: true
+ type: string
+ - name: sessionId
+ in: query
+ description: sessionId is the Unique identification of the client
+ type: string
+ - name: ip
+ in: query
+ description: client ip
+ type: string
+ - name: urlPath
+ in: query
+ description: address of the call
+ type: string
+ - name: userAgent
+ in: query
+ description: user agent of the call
+ type: string
+ consumes:
+ - application/json
+ - text/yaml
+ produces:
+ - application/json
+ - text/yaml
+ responses:
+ "200":
+ description: "true"
+ schema:
+ type: array
+ items:
+ $ref: '#/definitions/PollingDataResponse'
+ /v1/health:
+ get:
+ summary: health check return version and revision
+ operationId: HealthCheck
+ consumes:
+ - application/json
+ - text/yaml
+ produces:
+ - application/json
+ - text/yaml
+ responses:
+ "200":
+ description: ""
+ schema:
+ $ref: '#/definitions/DocHealthCheck'
definitions:
- v1.DocResponseGetKey:
+ DocHealthCheck:
+ type: object
+ properties:
+ revision:
+ type: string
+ timestamp:
+ type: integer
+ format: int64
+ version:
+ type: string
+ DocResponseGetKey:
type: object
properties:
data:
type: array
items:
- $ref: '#/definitions/v1.DocResponseSingleKey'
+ $ref: '#/definitions/DocResponseSingleKey'
total:
type: integer
format: int64
- v1.DocResponseSingleKey:
+ DocResponseSingleKey:
type: object
properties:
create_revision:
@@ -231,6 +317,44 @@ definitions:
type: string
value_type:
type: string
+ PollingDataResponse:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ $ref: '#/definitions/PollingDetail'
+ total:
+ type: integer
+ format: int32
+ PollingDetail:
+ type: object
+ properties:
+ domain:
+ type: string
+ id:
+ type: string
+ ip:
+ type: string
+ params:
+ type: object
+ additionalProperties:
+ type: string
+ response_body:
+ type: string
+ response_code:
+ type: integer
+ format: int32
+ response_header:
+ type: object
+ additionalProperties:
+ type: string
+ session_id:
+ type: string
+ url_path:
+ type: string
+ user_agent:
+ type: string
v1.KVBody:
type: object
properties:
diff --git a/server/resource/v1/doc_struct.go b/server/resource/v1/doc_struct.go
index 1a5aebb..4ae6620 100644
--- a/server/resource/v1/doc_struct.go
+++ b/server/resource/v1/doc_struct.go
@@ -24,7 +24,7 @@ import (
"github.com/go-chassis/go-chassis/server/restful"
)
-//swagger doc header params
+//swagger doc request header params
var (
DocHeaderDepth = &restful.Parameters{
DataType: "string",
@@ -32,6 +32,17 @@ var (
ParamType: goRestful.HeaderParameterKind,
Desc: "integer, default is 1, if you set match policy, you
can set,depth to decide label number",
}
+ DocHeaderContentType = &restful.Parameters{
+ DataType: "string",
+ Name: common.HeaderContentType,
+ ParamType: goRestful.HeaderParameterKind,
+ Required: true,
+ Desc: "used to indicate the media type of the resource,
the value can be application/json or text/yaml",
+ }
+)
+
+//swagger doc response header params
+var (
DocHeaderRevision = goRestful.Header{
Items: &goRestful.Items{
Type: "integer",
diff --git a/server/resource/v1/kv_resource.go
b/server/resource/v1/kv_resource.go
index e4d883e..1f83c12 100644
--- a/server/resource/v1/kv_resource.go
+++ b/server/resource/v1/kv_resource.go
@@ -258,7 +258,7 @@ func (r *KVResource) URLPatterns() []restful.Route {
ResourceFunc: r.Put,
FuncDesc: "create or update key value",
Parameters: []*restful.Parameters{
- DocPathProject, DocPathKey,
+ DocPathProject, DocPathKey,
DocHeaderContentType,
},
Read: KVBody{},
Returns: []*restful.Returns{
