When the completed interface is handed over to the frontend for invocation, it is necessary to prepare interface documentation for them. Fortunately, GoFrame has a built-in feature to automatically generate interface documentation, saving us a lot of time. By carrying some additional tags when writing api, beautiful documentation can be generated.

api/users/v1/users.go

package v1  
  
import "github.com/gogf/gf/v2/frame/g"  
  
type RegisterReq struct {  
    g.Meta   `path:"users/register" method:"post" sm:"Register" tags:"User"`  
    Username string `json:"username" v:"required|length:3,12" dc:"Username"`  
    Password string `json:"password" v:"required|length:6,16" dc:"Password"`  
    Email    string `json:"email" v:"required|email" dc:"Email"`  
}  
  
type RegisterRes struct {  
}

Open the browser at http://127.0.0.1:8000/swagger:

Another address http://127.0.0.1:8000/api.json provides interface documentation in Json format, which can be imported into various Api tools.

In addition to sm, tags, and dc tags, GoFrame also provides the following tags:

Common OpenAPIv3 Tags	Description	Note
path	Combines with the prefix registered to form the interface URI path	Used in g.Meta to identify interface metadata
tags	The tag to which the interface belongs for interface categorization	Used in g.Meta to identify interface metadata
method	The request method of the interface: GET/PUT/POST/DELETE... (case-insensitive)	Used in g.Meta to identify interface metadata
deprecated	Marks the interface as deprecated	Used in g.Meta to identify interface metadata
summary	Summary description of the interface/parameter	Abbreviated as sm
description	Detailed description of the interface/parameter	Abbreviated as dc
in	Method of parameter submission	header/path/query/cookie
default	Default value of the parameter	Abbreviated as d
mime	MIME type of the interface, such as multipart/form-data, generally set globally, default is application/json.	Used in g.Meta to identify interface metadata
type	Type of the parameter, generally does not need to be set, specific parameters need to be set manually, such as file	Only for parameter properties