Skip to content

Commit

Permalink
Merge pull request #30 from sunist-c/document
Browse files Browse the repository at this point in the history 
update document
  • Loading branch information
@sunist-c
sunist-c authored Jan 13, 2023
2 parents 0046a1e + 701b4d6 commit 1fa8b46
Show file tree
Hide file tree
Showing 7 changed files with 883 additions and 10 deletions.
10 changes: 5 additions & 5 deletions docs/_sidebar.md
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
* [首页](/)
* [开发文档](/development)
* [API文档](/development/api)
* [开发文档](/development/)
* [API文档](/development/api/)
* [房间](/development/api/room.md)
* [玩家](/development/api/player.md)
* [卡组](/development/api/card_deck.md)
* [本地化](/development/api/localization.md)
* [框架文档](/development/framework)
* [框架文档](/development/framework/)
* [战斗框架](/development/framework/battle.md)
* [通信框架](/development/framework/communication.md)
* [网络框架](/development/framework/network.md)
* [MOD文档](/development/mod)
* [MOD文档](/development/mod/)
* [MOD基础](/development/mod/guide.md)
* [制作卡牌](/development/mod/card.md)
* [制作角色](/development/mod/character.md)
Expand All @@ -19,7 +19,7 @@
* [制作支援物](/development/mod/support.md)
* [使用其他语言制作MOD](/development/mod/scripts.md)
* [发布MOD](/development/mod/publish.md)
* [使用文档](/guide)
* [使用文档](/guide/)
* [部署到服务器](/guide/deploy.md)
* [加载MOD](/guide/modify.md)
* [连接到服务器](/guide/connection.md)
77 changes: 77 additions & 0 deletions docs/development/api/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
这里是GISB的API文档，此文档为前后端开发人员提供关于GISB的 `HTTP` 服务的说明与解释

# 1. 状态码定义

GISB的后端使用HTTP状态码来表示请求的响应结果，大部分情况下，非 `200(Success)` 状态码都不会返回除状态码的任何信息

下面是GISB的HTTP服务对其返回状态码的说明：

**200(Success)**

此状态表明HTTP请求合法，且服务端响应过程正常，且返回数据正常

**400(BadRequest)**

此状态表明HTTP请求非法，您可以试着分析您的请求，是否将必须的参数提供完整提供，且请求体的格式正确无误

**403(Forbidden)**

此状态表明HTTP请求合法，但发起者对所请求的资源不具备访问权限，您可以试着分析您的请求，是否将鉴权相关的参数/cookie完整提供，或是请求的资源是否正确

**404(NotFound)**

此状态表明HTTP请求合法，但服务端不持有所请求资源，您可以检查您访问的资源是否正确

**412(PreconditionFailed)**

此状态表明HTTP请求合法，但发起者被服务器所限制，一般是由于您的请求频率过快或认证失败次数过多导致的，您可以等待一段时间后重新发起请求

**500(InternalError)**

此状态表明HTTP请求合法，但服务器在响应请求的过程中出现了错误，您可以将此错误反馈给服务器管理人员或本项目的开发者以寻求解决方法

# 2. 配置说明

GISB可以在启动前对其进行配置，此处对其进行说明与解释，配置的声明如下：

```go
type MiddlewareConfig struct {
UUIDKey string `json:"uuid_key" yaml:"uuid_key" xml:"uuid_key"`
IPTranceKey string `json:"ip_trace_key" yaml:"ip_trance_key" xml:"ip_trance_key"`
InterdictorTraceKey string `json:"interdictor_trace_key" yaml:"interdictor_trace_key" xml:"interdictor_trace_key"`
InterdictorBlockedTime uint `json:"interdictor_blocked_time" yaml:"interdictor_blocked_time" xml:"interdictor_blocked_time"`
InterdictorTriggerCount uint `json:"interdictor_trigger_count" yaml:"interdictor_trigger_count" xml:"interdictor_trigger_count"`
QPSLimitTime uint `json:"qps_limit_time" yaml:"qps_limit_time" xml:"qps_limit_time"`
TokenIDKey string `json:"token_id_key" yaml:"token_id_key" xml:"token_id_key"`
TokenKey string `json:"token_key" yaml:"token_key" xml:"token_key"`
TokenRefreshTime uint `json:"token_refresh_time" yaml:"token_refresh_time" xml:"token_refresh_time"`
TokenRemainingTime uint `json:"token_remaining_time" yaml:"token_remaining_time" xml:"token_remaining_time"`
CookieDomain string `json:"cookie_domain" yaml:"cookie_domain" xml:"cookie_domain"`
}
```

默认的配置如下：

```go
var (
config = &EngineConfig{
Middleware: MiddlewareConfig{
UUIDKey: "uuid",
IPTranceKey: "ip",
InterdictorTraceKey: "interdicted",
InterdictorBlockedTime: 600,
InterdictorTriggerCount: 5,
QPSLimitTime: 1,
TokenIDKey: "gisb_token_id",
TokenKey: "gisb_token",
TokenRefreshTime: 7200,
TokenRemainingTime: 1800,
CookieDomain: "localhost",
},
Service: ServiceConfig{
MaxRooms: 100,
},
}
}
)
```
281 changes: 281 additions & 0 deletions docs/development/api/card_deck.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,281 @@
此处为GISB的卡组相关服务，包含卡组的新增、修改、获取、删除等接口

# 变量与参数

+ `:card_deck_id`: 表示卡组的ID
+ `{gisb_token_id_value}`: 表示token_id在cookie中的值，由登录接口获取
+ `{gisb_token_value}`: 表示token在cookie中的键，由登录接口获取

# 说明

本文的所有接口均需要鉴权，您需要在请求中附带您的token

# 上传卡组

## 请求方法与地址

```plain text
POST {BaseURL}/card_deck
```

## 请求/响应

<!-- panels:start -->

<!-- div:left-panel -->

### 请求

您需要提供所要上传卡组的信息

#### 请求体定义

```go
type UploadCardDeckRequest struct {
Owner uint `json:"owner"`
RequiredPackage []string `json:"required_package"`
Cards []uint `json:"cards"`
Characters []uint `json:"characters"`
}
```

#### 请求示例

```http
POST /card_deck HTTP/1.1
Host: {BaseURL}
Content-Type: application/json
Cookie: gisb_token={gisb_token_value}; gisb_token_id={gisb_token_id_value}
Content-Length: 98
{
"owner": 1,
"required_package": ["base"],
"cards": [1],
"characters": [1]
}
```

<!-- div:right-panel -->

### 响应

此接口将尝试把您提供的卡组上传至持久化模块，并同步更新玩家信息

#### 响应体定义

```go
type UploadCardDeckResponse struct {
ID uint `json:"id"`
Owner uint `json:"owner"`
RequiredPackage []string `json:"required_package"`
Cards []uint `json:"cards"`
Characters []uint `json:"characters"`
}
```

#### 响应示例

```json
{
"id": 3,
"owner": 1,
"required_package": [
"base"
],
"cards": [
1
],
"characters": [
1
]
}
```

<!-- panels:end -->

# 获取卡组

## 请求方法与地址

```plain text
GET {BaseURL}/card_deck/:card_deck_id
```

## 请求/响应

<!-- panels:start -->

<!-- div:left-panel -->

### 请求

本接口不需要提供请求体

#### 请求示例

```http
GET /card_deck/:card_deck_id HTTP/1.1
Host: {BaseURL}
Cookie: gisb_token={gisb_token_value}; gisb_token_id={gisb_token_id_value}
```

<!-- div:right-panel -->

### 响应

此接口将查询并返回您所给定id的卡组

#### 响应体定义

```go
type QueryCardDeckResponse struct {
ID uint `json:"id"`
Owner uint `json:"owner"`
RequiredPackage []string `json:"required_package"`
Cards []uint `json:"cards"`
Characters []uint `json:"characters"`
}
```

#### 响应示例

```json
{
"id": 3,
"owner": 1,
"required_package": [
"base"
],
"cards": [
1
],
"characters": [
1
]
}
```

<!-- panels:end -->

# 更新卡组

## 请求方法与地址

```plain text
PUT {BaseURL}/card_deck/:card_deck_id
```

## 请求/响应

<!-- panels:start -->

<!-- div:left-panel -->

### 请求

您需要提供所要更新卡组的信息

#### 请求体定义

```go
type UpdateCardDeckRequest struct {
Owner uint `json:"owner"`
RequiredPackage []string `json:"required_package"`
Cards []uint `json:"cards"`
Characters []uint `json:"characters"`
}
```

#### 请求示例

```http
PUT /card_deck/:card_deck_id HTTP/1.1
Host: {BaseURL}
Content-Type: application/json
Cookie: gisb_token={gisb_token_value}; gisb_token_id={gisb_token_id_value}
Content-Length: 101
{
"owner": 1,
"required_package": ["enhance"],
"cards": [1],
"characters": [1]
}
```

<!-- div:right-panel -->

### 响应

此接口将根据您所给定的id尝试更新卡组，并将结果返回

#### 响应体定义

```go
type UpdateCardDeckResponse struct {
ID uint `json:"id"`
Owner uint `json:"owner"`
RequiredPackage []string `json:"required_package"`
Cards []uint `json:"cards"`
Characters []uint `json:"characters"`
}
```

#### 响应示例

```json
{
"id": 3,
"owner": 1,
"required_package": [
"enhance"
],
"cards": [
1
],
"characters": [
1
]
}
```

<!-- panels:end -->

# 删除卡组

## 请求方法与地址

```plain text
DELETE {BaseURL}/card_deck/:card_deck_id
```

## 请求/响应

<!-- panels:start -->

<!-- div:left-panel -->

### 请求

本接口不需要提供请求体

#### 请求示例

```http
DELETE /card_deck/:card_deck_id HTTP/1.1
Host: {BaseURL}
Cookie: gisb_token={gisb_token_value}; gisb_token_id={gisb_token_id_value}
```

<!-- div:right-panel -->

### 响应

此接口将根据您给定的id尝试删除卡组

#### 响应体定义

本接口没有响应体，返回HTTP Status 200即表明删除成功

<!-- panels:end -->
Loading

0 comments on commit 1fa8b46

Please sign in to comment.