Skip to content

feat: support JSON array request bodies with type:"array" tag and enh… #294

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
qinains wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: support JSON array request bodies with type:"array" tag and enh… #294

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 151 additions & 2 deletions docs/docs/WEB服务开发/接口文档/接口文档-OpenAPIv3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,11 +43,160 @@ import TabItem from '@theme/TabItem';
| `in` | 参数的提交方式 | `header/path/query/cookie` |
| `default` | 参数的默认值 | 缩写 `d` |
| `mime` | 接口的 `MIME` 类型，例如 `multipart/form-data` 一般是全局设置，默认为 `application/json`。 | 用于 `g.Meta` 标识接口元数据 |
| `type` | 参数的类型，一般不需要设置，特殊参数需要手动设置，例如 `file` | 仅用于参数属性 |
| `type` | 参数的类型，一般不需要设置。常用值：`file` 用于文件上传字段；`array` 用于请求体，表示请求体为 JSON 数组格式 `[{}]` 而非对象格式 `{}` | `file` 仅用于参数属性；`array` 仅用于 `g.Meta` |
:::tip
更多标签请参考标准的 `OpenAPIv3` 协议： [https://swagger.io/specification/](https://swagger.io/specification/)
:::

### 2、`type:"array"` 数组请求体支持

当接口需要接收 JSON 数组格式的请求体时，可以在 `g.Meta` 中使用 `type:"array"` 标签。这在批量数据处理、批量操作等场景中非常有用。

#### 2.1 使用示例

```go
package main

import (
"context"

"github.com/gogf/gf/v2/frame/g"
"github.com/gogf/gf/v2/net/ghttp"
)

// 聊天消息请求结构
type ChatMessage struct {
Role string `json:"role" dc:"角色: system/user/assistant"`
Content string `json:"content" dc:"消息内容"`
}

// 批量聊天请求
type BatchChatReq struct {
g.Meta `mime:"application/json" method:"post" path:"/batch/chat" type:"array" summary:"批量聊天接口"`
Messages []ChatMessage `json:"messages" dc:"消息列表"`
}

type BatchChatRes struct {
Results []string `json:"results" dc:"处理结果"`
}

type Controller struct{}

func (c *Controller) BatchChat(ctx context.Context, req *BatchChatReq) (res *BatchChatRes, err error) {
// 处理批量消息
res = &BatchChatRes{
Results: make([]string, len(req.Messages)),
}
for i, msg := range req.Messages {
res.Results[i] = "Role: " + msg.Role + ", Content: " + msg.Content
}
return
}

func main() {
s := g.Server()
s.Group("/", func(group *ghttp.RouterGroup) {
group.Bind(new(Controller))
})
s.SetOpenApiPath("/api.json")
s.SetSwaggerPath("/swagger")
s.SetPort(8199)
s.Run()
}
```

#### 2.2 请求体格式

使用 `type:"array"` 后，请求体应为 JSON 数组格式：

```json
[
{"role": "user", "content": "hello"},
{"role": "assistant", "content": "world"}
]
```

生成的 `OpenAPIv3` 文档中，请求体的 `schema.type` 将为 `"array"`，而不会生成对象类型的 Components Schema。

#### 2.3 嵌套结构支持

`type:"array"` 完全支持嵌套结构，包括对象嵌套和数组嵌套：

```go
package main

import (
"context"

"github.com/gogf/gf/v2/frame/g"
"github.com/gogf/gf/v2/net/ghttp"
)

// 嵌套结构 - 额外信息
type ExtraInfo struct {
Key1 string `json:"key1" dc:"键1"`
Key2 int `json:"key2" dc:"键2"`
Tags []string `json:"tags" dc:"标签列表"`
}

// 嵌套结构 - 聊天消息
type ChatMessage struct {
Role string `json:"role" dc:"角色: system/user/assistant"`
Content string `json:"content" dc:"消息内容"`
Extra ExtraInfo `json:"extra" dc:"额外信息"`
}

// 批量聊天请求
type BatchChatReq struct {
g.Meta `mime:"application/json" method:"post" path:"/batch/chat" type:"array" summary:"批量聊天接口"`
Messages []ChatMessage `json:"messages" dc:"消息列表"`
}

type Controller struct{}

func (c *Controller) BatchChat(ctx context.Context, req *BatchChatReq) (res *BatchChatRes, err error) {
// 处理嵌套结构
for _, msg := range req.Messages {
println("Role:", msg.Role)
println("Content:", msg.Content)
println("Extra.Key1:", msg.Extra.Key1)
println("Extra.Tags:", msg.Extra.Tags)
}
return
}
```

**嵌套 JSON 请求体示例：**

```json
[
{
"role": "user",
"content": "hello",
"extra": {
"key1": "value1",
"key2": 123,
"tags": ["tag1", "tag2"]
}
},
{
"role": "assistant",
"content": "world",
"extra": {
"key1": "value2",
"key2": 456,
"tags": ["tag3"]
}
}
]
```

#### 2.4 注意事项

- `type:"array"` 需要与 `mime:"application/json"` 配合使用
- 请求体会直接解析到结构体中的切片字段
- 与 `type:"file"` 互斥，不应同时使用

<!--

除此之外，响应结构体的 `g.Meta` 还支持额外的标签以设置更详细的文档信息：
Expand Down Expand Up @@ -97,7 +246,7 @@ import TabItem from '@theme/TabItem';

-->

### 2、扩展标签
### 3、扩展标签

在 `OpenAPI` 规范里面，所有名称以 `x-` 开头的标签是开发者可自定义的扩展标签。扩展标签可以在任意的接口、属性中以 `Golang struct tag` 的形式定义，在接口文档生成时，将会作为独立的字段返回。例如：

Expand Down
172 changes: 138 additions & 34 deletions i18n/en/docusaurus-plugin-content-docs/current/docs/WEB服务开发/接口文档/接口文档-OpenAPIv3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,57 +43,161 @@ Commonly used basic tags include:
| `in` | Parameter submission method | `header/path/query/cookie` |
| `default` | Default value for the parameter | Abbreviation `d` |
| `mime` | The `MIME` type of the API, such as `multipart/form-data`, generally set globally, defaults to `application/json`. | Used for `g.Meta` to mark API metadata |
| `type` | The type of the parameter, generally not needed, special parameters may require manual setting, such as `file` | Only applicable to parameter attributes |
| `type` | The type of the parameter. Common values: `file` for file upload fields; `array` for request body, indicating the request body is JSON array format `[{}]` instead of object format `{}` | `file` only for parameter attributes; `array` only for `g.Meta` |
:::tip
For more tags, please refer to the standard `OpenAPIv3` protocol: [https://swagger.io/specification/](https://swagger.io/specification/)
:::

In addition to the above tags, the `g.Meta` of the response structure also supports additional tags to set more detailed documentation information:
### 2. `type:"array"` Array Request Body Support

| Tag | Description | Remarks |
| --- | --- | --- |
| `status` | Set the default return status code of the response | Used for `g.Meta` to mark API metadata, default value is `200` |
| `responseExample` | Set the `json` file path of the default return example of the response | Used for `g.Meta` to mark API metadata, abbreviation `resEg` |
When an API needs to receive JSON array format request body, you can use `type:"array"` tag in `g.Meta`. This is very useful in batch data processing, batch operations, and other scenarios.

#### 2.1 Usage Example

```go
package main

import (
"context"

"github.com/gogf/gf/v2/frame/g"
"github.com/gogf/gf/v2/net/ghttp"
)

// Chat message request structure
type ChatMessage struct {
Role string `json:"role" dc:"Role: system/user/assistant"`
Content string `json:"content" dc:"Message content"`
}

// Batch chat request
type BatchChatReq struct {
g.Meta `mime:"application/json" method:"post" path:"/batch/chat" type:"array" summary:"Batch chat API"`
Messages []ChatMessage `json:"messages" dc:"Message list"`
}

The `json` file formats supported by `responseExample` are as follows:
type BatchChatRes struct {
Results []string `json:"results" dc:"Processing results"`
}

type Controller struct{}

func (c *Controller) BatchChat(ctx context.Context, req *BatchChatReq) (res *BatchChatRes, err error) {
// Handle batch messages
res = &BatchChatRes{
Results: make([]string, len(req.Messages)),
}
for i, msg := range req.Messages {
res.Results[i] = "Role: " + msg.Role + ", Content: " + msg.Content
}
return
}

func main() {
s := g.Server()
s.Group("/", func(group *ghttp.RouterGroup) {
group.Bind(new(Controller))
})
s.SetOpenApiPath("/api.json")
s.SetSwaggerPath("/swagger")
s.SetPort(8199)
s.Run()
}
```

#### 2.2 Request Body Format

After using `type:"array"`, the request body should be in JSON array format:

<Tabs>
<TabItem value="array" label="Array">
```json
[
{
"code": 0,
"message": "Success",
"data": null
},
{
"code": 1,
"message": "Internal Server Error",
"data": null
}
{"role": "user", "content": "hello"},
{"role": "assistant", "content": "world"}
]
```
</TabItem>
<TabItem value="object" label="Object">

In the generated `OpenAPIv3` documentation, the request body's `schema.type` will be `"array"`, and will not generate object-type Components Schema.

#### 2.3 Nested Structure Support

`type:"array"` fully supports nested structures, including object nesting and array nesting:

```go
package main

import (
"context"

"github.com/gogf/gf/v2/frame/g"
"github.com/gogf/gf/v2/net/ghttp"
)

// Nested structure - extra information
type ExtraInfo struct {
Key1 string `json:"key1" dc:"Key 1"`
Key2 int `json:"key2" dc:"Key 2"`
Tags []string `json:"tags" dc:"Tags list"`
}

// Nested structure - chat message
type ChatMessage struct {
Role string `json:"role" dc:"Role: system/user/assistant"`
Content string `json:"content" dc:"Message content"`
Extra ExtraInfo `json:"extra" dc:"Extra information"`
}

// Batch chat request
type BatchChatReq struct {
g.Meta `mime:"application/json" method:"post" path:"/batch/chat" type:"array" summary:"Batch chat API"`
Messages []ChatMessage `json:"messages" dc:"Message list"`
}

type Controller struct{}

func (c *Controller) BatchChat(ctx context.Context, req *BatchChatReq) (res *BatchChatRes, err error) {
// Handle nested structures
for _, msg := range req.Messages {
println("Role:", msg.Role)
println("Content:", msg.Content)
println("Extra.Key1:", msg.Extra.Key1)
println("Extra.Tags:", msg.Extra.Tags)
}
return
}
```

**Nested JSON Request Body Example:**

```json
{
"success": {
"code": 0,
"message": "Success",
"data": null
[
{
"role": "user",
"content": "hello",
"extra": {
"key1": "value1",
"key2": 123,
"tags": ["tag1", "tag2"]
}
},
"error": {
"code": 1,
"message": "Internal Server Error",
"data": null
{
"role": "assistant",
"content": "world",
"extra": {
"key1": "value2",
"key2": 456,
"tags": ["tag3"]
}
}
}
]
```
</TabItem>
</Tabs>

#### 2.4 Notes

- `type:"array"` needs to be used with `mime:"application/json"`
- The request body will be directly parsed to the slice field in the structure
- Mutually exclusive with `type:"file"`, should not be used together

### 2. Extension Tags
### 3. Extension Tags

In the `OpenAPI` specification, all tags prefixed with `x-` are customizable extension tags by developers. Extension tags can be defined in any API or attribute using `Golang struct tag` format, and during the generation of API documentation, they will be returned as independent fields. For example:

Expand Down
Loading