Skip to content

Commit

Permalink
更新 bk-apigateway 网关 API 文档 (#128)
Browse files Browse the repository at this point in the history
  • Loading branch information
@alex-smile
alex-smile authored Jul 21, 2023
1 parent 2edeb24 commit f159824
Show file tree
Hide file tree
Showing 11 changed files with 80 additions and 60 deletions.
12 changes: 6 additions & 6 deletions ...ashboard/apigateway/apigateway/editions/ee/data/apidocs/zh/apply_permissions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,12 @@

#### 请求参数

| 参数名称 | 参数类型 | 必选 | 描述 |
| --------------- | -------- | ---- | ------------------------------------------------------- |
| target_app_code | string | 是 | 申请权限的应用，应于当前请求的应用一致 |
| expire_days | int | 否 | 过期时间，0 表示永久，180 表示 6 个月，360 表示 12 个月 |
| grant_dimension | string | 是 | 授权维度，api 表示按网关申请权限 |
| reason | string | 否 | 申请原因 |
| 参数名称 | 参数类型 | 必选 | 描述 |
| --------------- | -------- | ---- | ---------------------------------------------------------------- |
| target_app_code | string | 是 | 申请权限的应用，应于当前请求的应用一致 |
| expire_days | int | 否 | 过期时间，0 或未提供 表示永久，180 表示 6 个月，360 表示 12 个月 |
| grant_dimension | string | 是 | 授权维度，api 表示按网关申请权限 |
| reason | string | 否 | 申请原因 |


### 请求参数示例
Expand Down
1 change: 1 addition & 0 deletions ...rd/apigateway/apigateway/editions/ee/data/apidocs/zh/create_resource_version.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ result = client.api.create_resource_version(
{
"version": "1.0.0",
"title": "发布新版本",
"comment": "这是一个什么样的新版本"
},
path_params={
"api_name": "demo",
Expand Down
19 changes: 10 additions & 9 deletions src/dashboard/apigateway/apigateway/editions/ee/data/apidocs/zh/generate_sdk.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,20 +12,19 @@

#### 请求参数

| 参数名称 | 参数类型 | 必选 | 描述 |
| ------------------------- | ------------- | ---- | -------------------------------------------------------- |
| resource_version | string | 是 | 资源版本的版本号 |
| languages | array[string] | 否 | 需要生成SDK的语言列表，可选值：python，默认为 python SDK |
| include_private_resources | boolean | 否 | 是否包含私有资源，默认为 false |
| version | string | 否 | SDK 版本号，未设置时，将使用资源版本的版本号 |

| 参数名称 | 参数类型 | 必选 | 描述 |
| ---------------- | ------------- | ---- | -------------------------------------------------------- |
| resource_version | string | 是 | 资源版本的版本号 |
| languages | array[string] | 否 | 需要生成SDK的语言列表，可选值：python，默认为 python SDK |
| version | string | 否 | SDK 版本号，未设置时，将使用资源版本的版本号 |

### 请求参数示例

```json
{
"resource_version": "1.0.1",
"languages": ["python"]
"languages": ["python"],
"version": "1.0.1"
}
```

Expand All @@ -37,7 +36,9 @@ from bkapi.bk_apigateway.shortcuts import get_client_by_request
client = get_client_by_request(request)
result = client.api.generate_sdk(
{
"resource_version": "1.0.1"
"resource_version": "1.0.1",
"languages": ["python"],
"version": "1.0.1"
}
)
```
Expand Down
18 changes: 7 additions & 11 deletions src/dashboard/apigateway/apigateway/editions/ee/data/apidocs/zh/get_apis.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,7 @@ result = client.api.get_apis({})
"description": "",
"maintainers": [
"admin"
],
"api_type": 10,
"user_auth_type": "default"
]
}
]
}
Expand All @@ -52,11 +50,9 @@ result = client.api.get_apis({})

#### data

| 参数名称 | 参数类型 | 描述 |
| -------------- | -------- | ----------------------------------- |
| id | int | 网关ID |
| name | string | 网关名称 |
| description | string | 网关描述 |
| maintainers | array | 网关管理员 |
| api_type | int | 网关类型，可选值: 10(普通网关) |
| user_auth_type | string | 用户类型，可选值：default(蓝鲸用户) |
| 参数名称 | 参数类型 | 描述 |
| ----------- | -------- | ---------- |
| id | int | 网关ID |
| name | string | 网关名称 |
| description | string | 网关描述 |
| maintainers | array | 网关管理员 |
11 changes: 6 additions & 5 deletions ...ard/apigateway/apigateway/editions/ee/data/apidocs/zh/get_released_resources.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,11 +71,12 @@ result = client.api.get_released_resources(

#### data

| 参数名称 | 参数类型 | 描述 |
| ----------------- | -------- | -------------------- |
| data.count | int | 资源数量 |
| data.has_next | boolean | 分页，后续是否有数据 |
| data.has_previous | boolean | 分页，前面是否有数据 |
| 参数名称 | 参数类型 | 描述 |
| ------------ | -------- | ---------------------------------------- |
| count | int | 资源数量 |
| has_next | boolean | 分页，后续是否有数据 |
| has_previous | boolean | 分页，前面是否有数据 |
| results | array | 本次查询的结果数据，详细信息请见下面说明 |

data.results 中字段说明

Expand Down
16 changes: 8 additions & 8 deletions ...ashboard/apigateway/apigateway/editions/ee/data/apidocs/zh/grant_permissions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,18 +13,18 @@

#### 请求参数

| 参数名称 | 参数类型 | 必选 | 描述 |
| --------------- | -------- | ---- | --------------------------------------------------------- |
| target_app_code | string | 是 | 待授权应用 |
| expire_days | int | 否 | 过期时间，单位天 |
| grant_dimension | string | 是 | 授权维度，可选值：api(按网关授权)，resource（按资源授权） |
| resource_names | array | 否 | 按资源授权时，需指定待授权的资源名列表 |
| 参数名称 | 参数类型 | 必选 | 描述 |
| --------------- | -------- | ---- | ----------------------------------------- |
| target_app_code | string | 是 | 待授权应用 |
| expire_days | int | 否 | 过期时间，单位天；0或不提供时表示永久权限 |
| grant_dimension | string | 是 | 授权维度，可选值：api(按网关授权) |

### 请求参数示例

```json
{
"target_app_code": "bk-sops",
"expire_days": 360,
"grant_dimension": "api"
}
```
Expand All @@ -38,8 +38,8 @@ client = get_client_by_request(request)
result = client.api.grant_permissions(
{
"target_app_code": "bk-sops",
"grant_dimension": "resource",
"resource_names": ["get_color", "create_color"]
"expire_days": 360,
"grant_dimension": "api",
},
path_params={
"api_name": "demo",
Expand Down
30 changes: 24 additions & 6 deletions ...ard/apigateway/apigateway/editions/ee/data/apidocs/zh/list_resource_versions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,19 @@

#### 请求参数

| 参数名称 | 参数类型 | 必选 | 描述 |
| -------- | -------- | ---- | ------ |
| version | string | 否 | 版本号 |
| 参数名称 | 参数类型 | 必选 | 描述 |
| -------- | -------- | ---- | ---------------------------------------- |
| version | string | 否 | 版本号 |
| limit | int | 否 | 最大返回条目数量，默认为 10 |
| offset | int | 否 | 相对于完整未分页数据的起始位置，默认为 0 |

### 请求参数示例

```json
{
"version": "1.0.0"
"version": "1.0.0",
"limit": 10,
"offset": 0
}
```

Expand All @@ -30,7 +34,13 @@
from bkapi.bk_apigateway.shortcuts import get_client_by_request

client = get_client_by_request(request)
result = client.api.list_resource_versions({"version": "1.0.0"})
result = client.api.list_resource_versions(
{
"version": "1.0.0",
"limit": 10,
"offset": 0
}
)
```


Expand All @@ -51,7 +61,6 @@ result = client.api.list_resource_versions({"version": "1.0.0"})
]
},
"code": 0,
"result": true,
"message": "OK"
}
```
Expand All @@ -64,6 +73,15 @@ result = client.api.list_resource_versions({"version": "1.0.0"})
| message | string | 错误信息 |
| data | array | 结果数据，详细信息请见下面说明 |

#### data

| 字段 | 类型 | 描述 |
| ------------ | ------- | ---------------------------------------- |
| count | int | 数据数量 |
| has_next | boolean | 分页，后续是否有数据 |
| has_previous | boolean | 分页，前面是否有数据 |
| results | array | 本次查询的结果数据，详细信息请见下面说明 |

#### data.results

| 参数名称 | 参数类型 | 描述 |
Expand Down
4 changes: 2 additions & 2 deletions ...shboard/apigateway/apigateway/editions/ee/data/apidocs/zh/revoke_permissions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@

```json
{
"target_app_codes": ["bk-sops"],
"target_app_codes": ["my-app"],
"grant_dimension": "api"
}
```
Expand All @@ -34,7 +34,7 @@ from bkapi.bk_apigateway.shortcuts import get_client_by_request
client = get_client_by_request(request)
result = client.api.revoke_permissions(
{
"target_app_codes": ["bk-sops"],
"target_app_codes": ["my-app"],
"grant_dimension": "api"
},
path_params={
Expand Down
13 changes: 7 additions & 6 deletions src/dashboard/apigateway/apigateway/editions/ee/data/apidocs/zh/sync_api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,11 @@

#### 请求参数

| 参数名称 | 参数类型 | 必选 | 描述 |
| -------------- | -------- | ---- | ----------------------------------- |
| description | string | 是 | 网关描述 |
| maintainers | array | 否 | 网关管理员 |
| is_public | boolean | 否 | 网关是否公开，默认公开 |
| user_auth_type | string | 否 | 用户类型，可选值：default(蓝鲸用户) |
| 参数名称 | 参数类型 | 必选 | 描述 |
| ----------- | -------- | ---- | ---------------------- |
| description | string | 是 | 网关描述 |
| maintainers | array | 否 | 网关管理员 |
| is_public | boolean | 否 | 网关是否公开，默认公开 |

### 请求参数示例

Expand All @@ -39,6 +38,8 @@ client = get_client_by_request(request)
result = client.api.sync_api(
{
"description": "just for test",
"maintainers": ["admin"],
"is_public": True
},
path_params={
"api_name": "demo",
Expand Down
13 changes: 7 additions & 6 deletions src/dashboard/apigateway/apigateway/editions/ee/data/apidocs/zh/sync_resources.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@ from bkapi.bk_apigateway.shortcuts import get_client_by_request
client = get_client_by_request(request)
result = client.api.sync_resources(
{
"content": "xxx"
"content": "xxx",
"delete": False
},
path_params={
"api_name": "demo",
Expand Down Expand Up @@ -69,8 +70,8 @@ result = client.api.sync_resources(

#### data

| 参数名称 | 参数类型 | 描述 |
| -------- | -------- | ---------- |
| added | array | 新增的资源 |
| updated | array | 更新的资源 |
| deleted | array | 删除的资源 |
| 参数名称 | 参数类型 | 描述 |
| -------- | -------- | ----------------------------------- |
| added | array | 新增的资源，其中数据，id 表示资源ID |
| updated | array | 更新的资源，其中数据，id 表示资源ID |
| deleted | array | 删除的资源，其中数据，id 表示资源ID |
3 changes: 2 additions & 1 deletion ...oard/apigateway/apigateway/editions/ee/data/apidocs/zh/update_gateway_status.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,4 +58,5 @@ result = client.api.update_gateway_status(
| 字段 | 类型 | 描述 |
| ------- | ------ | ---------------------------------- |
| code | int | 返回码，0 表示成功，其它值表示失败 |
| message | string | 错误信息 |
| message | string | 错误信息 |
| data | object | 空 |

0 comments on commit f159824

Please sign in to comment.