接口文档-扩展Response
一、概述
RESTful API设计中，不同的状态码表示不同的响应情况，例如 200 表示成功，201 表示创建成功，400 表示请求错误，401 表示未授权等。在GoFrame的OpenAPIv3接口文档中，默认情况下只会生成成功状态（通常是 200）的响应文档。
然而，在实际应用中，我们常常需要为一个API提供多种可能的响应状态，例如错误处理、权限验证失败等情况。为了满足这一需求，GoFrame在 goai 组件中提供了 IEnhanceResponseStatus 接口，开发者可以通过实现该接口来扩展响应结构体的信息，添加多种状态码的响应文档。
二、接口定义
IEnhanceResponseStatus 接口的相关定义如下：
type EnhancedStatusCode = int
type EnhancedStatusType struct {
Response any
Examples any
}
type IEnhanceResponseStatus interface {
EnhanceResponseStatus() map[EnhancedStatusCode]EnhancedStatusType
}三、接口字段说明
EnhancedStatusCode：表示 HTTP 状态码，例如200、201、400、401、403、404、500等。EnhancedStatusType：包含两个字段：Response：响应结构体，可以是任意类型（any）。你可以为它添加g.Meta标签来添加文档信息，如果设置了mime标签，该结构体会覆盖通用响应结构体的内容。Examples：响应示例，可以是任意类型（any）。你可以使用错误码列表自动生成示例内容并显示在文档中，这样可以保证文档内容与实际业务内容的同步。
IEnhanceResponseStatus：接口定义，包含一个方法EnhanceResponseStatus()，该方法返回一个映射，将 HTTP 状态码映射到相应的EnhancedStatusType类型。
四、使用方法
要使用 IEnhanceResponseStatus 接口，需要在响应结构体中实现 EnhanceResponseStatus() 方法。该方法返回一个映射，将 HTTP 状态码映射到相应的响应结构体和示例。
1. 实现接口
在响应结构体中实现 EnhanceResponseStatus() 方法，返回不同状态码对应的响应结构体和示例。
2. 设置响应状态码
可以在响应结构体的 g.Meta 标签中使用 status 属性来设置默认的响应状态码，例如 g.Meta status:"201"`。
3. 使用示例数据
可以在 EnhanceResponseStatus() 方法中返回示例数据，这些数据将会显示在生成的 OpenAPIv3 文档中。
五、完整示例
下面是一个完整的示例，演示如何使用 IEnhanceResponseStatus 接口来扩展响应结构体的信息：
package main
import (
"context"
"github.com/gogf/gf/v2/errors/gcode"
"github.com/gogf/gf/v2/errors/gerror"
"github.com/gogf/gf/v2/frame/g"
"github.com/gogf/gf/v2/net/ghttp"
"github.com/gogf/gf/v2/net/goai"
)
type StoreMessageReq struct {
g.Meta `path:"/messages" method:"post" summary:"Store a message"`
Content string `json:"content"`
}
type StoreMessageRes struct {
g.Meta `status:"201"`
Id string `json:"id"`
}
type EmptyRes struct {
g.Meta `mime:"application/json"`
}
type CommonRes struct {
Code int `json:"code"`
Message string `json:"message"`
Data interface{} `json:"data"`
}
var StoreMessageErr = map[int]gcode.Code{
500: gcode.New(1, "Server Dead", nil),
}
func (r StoreMessageRes) EnhanceResponseStatus() (resList map[int]goai.EnhancedStatusType) {
examples := []interface{}{}
example500 := CommonRes{
Code: StoreMessageErr[500].Code(),
Message: StoreMessageErr[500].Message(),
Data: nil,
}
examples = append(examples, example500)
return map[int]goai.EnhancedStatusType{
403: {
Response: EmptyRes{},
},
500: {
Response: struct{}{},
Examples: examples,
},
}
}
type Controller struct{}
func (c *Controller) StoreMessage(ctx context.Context, req *StoreMessageReq) (res *StoreMessageRes, err error) {
return nil, gerror.NewCode(gcode.CodeNotImplemented)
}
func main() {
s := g.Server()
s.Group("/", func(group *ghttp.RouterGroup) {
group.Bind(new(Controller))
})
oai := s.GetOpenApi()
oai.Config.CommonResponse = CommonRes{}
oai.Config.CommonResponseDataField = `Data`
s.SetOpenApiPath("/api.json")
s.SetSwaggerPath("/swagger")
s.SetPort(8199)
s.Run()
}执行后，访问地址 http://127.0.0.1:8199/swagger 可以查看 swagger ui，访问 http://127.0.0.1:8199/api.json 可以查看对应的 OpenAPIv3 接口文档。其中生成的 OpenAPIv3 接口文档如下：
{
"openapi": "3.0.0",
"components": {
"schemas": {
"main.StoreMessageReq": {
"properties": {
"content": {
"format": "string",
"type": "string"
}
},
"type": "object"
},
"main.StoreMessageRes": {
"properties": {
"id": {
"format": "string",
"type": "string"
}
},
"type": "object"
},
"interface": {
"properties": {},
"type": "object"
},
"main.EmptyRes": {
"properties": {},
"type": "object"
},
"struct": {
"properties": {},
"type": "object"
}
}
},
"info": {
"title": "",
"version": ""
},
"paths": {
"/messages": {
"post": {
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/main.StoreMessageReq"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"format": "int",
"type": "integer"
},
"message": {
"format": "string",
"type": "string"
},
"data": {
"properties": {
"id": {
"format": "string",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"description": ""
},
"403": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/main.EmptyRes"
}
}
},
"description": ""
},
"500": {
"content": {
"application/json": {
"schema": {
"properties": {
"code": {
"format": "int",
"type": "integer"
},
"message": {
"format": "string",
"type": "string"
},
"data": {
"properties": {},
"type": "object"
}
},
"type": "object"
},
"examples": {
"example 1": {
"value": {
"code": 1,
"message": "Server Dead",
"data": null
}
}
}
}
},
"description": ""
}
},
"summary": "Store a message"
}
}
}
}可以看到默认的响应状态码已经被更改为 201，并且响应示例也自动生成。
六、常见状态码使用场景
在实际应用中，不同的 HTTP 状态码用于表示不同的响应情况。以下是一些常见的状态码及其使用场景：
200 OK：请求成功，返回请求的数据。201 Created：资源创建成功，通常用于 POST 请求。204 No Content：请求成功，但没有返回内容，通常用于 DELETE 请求。400 Bad Request：请求参数错误或格式不正确。401 Unauthorized：未授权，需要身份验证。403 Forbidden：已授权，但没有权限访问资源。404 Not Found：请求的资源不存在。500 Internal Server Error：服务器内部错误。
在实现 IEnhanceResponseStatus 接口时，可以根据实际业务需求，为这些不同的状态码提供相应的响应结构体和示例数据。
七、使用建议
结构体复用：对于类似的响应结构，可以定义公共的结构体进行复用，减少代码重复。
错误码管理：将错误码集中管理，例如使用
map或常量来定义不同状态码对应的错误码，便于维护和扩展。示例数据的真实性：提供的示例数据应尽量真实，反映实际业务场景，便于前端开发者理解和处理。
文档同步更新：当业务逻辑或错误码变更时，及时更新接口文档，保持文档与代码的一致性。
八、使用资源文件加载示例数据
在实际应用中，示例数据可能会比较大或复杂，直接在代码中编写可能会影响代码的可读性。GoFrame的goai组件提供了从外部文件加载示例数据的功能，支持从gres资源管理器或本地文件系统中读取示例数据，文件格式可以为json/xml/yaml/ini等gjson组件支持的格式。
1. 使用g.Meta标签指定示例文件
可以在响应结构体的g.Meta标签中使用resEg属性指定示例文件的路径：
type MyResponse struct {
g.Meta `status:"201" resEg:"testdata/examples/201.json"`
// ...其他字段
}其中testdata/examples/201.json是示例文件的路径，可以是相对路径或绝对路径。
2. 示例文件格式
示例文件可以是一个JSON对象或JSON数组：
JSON对象：每个键将作为示例的名称，值作为示例的内容。
{ "example1": { "code": 0, "message": "Success", "data": { "id": 1 } }, "example2": { "code": 1, "message": "Failed", "data": null } }JSON数组：数组中的每个元素将作为一个示例，示例名称会自动生成为
example 1、example 2等。[ { "code": 0, "message": "Success", "data": { "id": 1 } }, { "code": 1, "message": "Failed", "data": null } ]
3. 使用gres资源管理器
GoFrame的goai组件会首先尝试从gres资源管理器中读取指定路径的文件，如果找不到，则会尝试从本地文件系统中读取。这使得可以将示例数据打包到程序中，方便分发和部署。
要使用gres资源管理器，需要先将示例文件打包到资源文件中：
package main
import (
"github.com/gogf/gf/v2/os/gres"
"github.com/gogf/gf/v2/frame/g"
)
func main() {
// 打包资源文件
gres.Dump()
// 初始化服务器
s := g.Server()
// ...其他配置
s.Run()
}4. 完整示例
下面是一个使用资源文件加载示例数据的完整示例：
package main
import (
"context"
"github.com/gogf/gf/v2/frame/g"
"github.com/gogf/gf/v2/net/ghttp"
)
type CreateUserReq struct {
g.Meta `path:"/users" method:"post" summary:"创建用户"`
Name string `json:"name" v:"required" dc:"用户名"`
Email string `json:"email" v:"required|email" dc:"电子邮箱"`
}
type CreateUserRes struct {
g.Meta `status:"201" resEg:"testdata/examples/user/create_success.json"`
Id int `json:"id" dc:"用户ID"`
}
func (r CreateUserRes) EnhanceResponseStatus() map[int]goai.EnhancedStatusType {
return map[int]goai.EnhancedStatusType{
400: {
Response: struct{}{},
// 从文件中加载错误示例
},
500: {
Response: struct{}{},
// 从文件中加载错误示例
},
}
}
type Controller struct{}
func (c *Controller) CreateUser(ctx context.Context, req *CreateUserReq) (res *CreateUserRes, err error) {
// 实际业务逻辑
return &CreateUserRes{Id: 1}, nil
}
func main() {
s := g.Server()
s.Group("/", func(group *ghttp.RouterGroup) {
group.Bind(new(Controller))
})
s.SetOpenApiPath("/api.json")
s.SetSwaggerPath("/swagger")
s.Run()
}其中testdata/examples/user/create_success.json文件内容可能是：
{
"成功示例": {
"code": 0,
"message": "创建成功",
"data": {
"id": 1
}
}
}这种方式可以使示例数据与代码分离，更容易维护和管理。
九、总结
GoFrame的 IEnhanceResponseStatus 接口提供了一种灵活、强大的方式来扩展 OpenAPIv3接口文档中的响应信息。通过实现该接口，开发者可以：
- 为
API提供多种响应状态的文档，使文档更符合RESTful API设计规范。 - 自定义不同状态码的响应结构体，提供更精确的接口定义。
- 通过示例数据展示不同状态的响应格式，便于前端开发者理解和处理。
- 保持文档与代码的一致性，提高开发效率和协作质量。
通过合理使用 IEnhanceResponseStatus 接口，可以显著提升API文档的质量和完整性，为前后端开发者提供更好的开发体验。