The OpenAPIv3 protocol is mainly used in standardized routing. Before reading the introduction to the API documentation protocol, please familiarize yourself with the standardized routing: Standard Router
I. OpenAPIv3
For a detailed introduction to the OpenAPIv3 protocol, please refer to: https://swagger.io/specification/
II. g.Meta Metadata
API metadata information can be implemented by embedding the g.Meta structure in the input struct and using its attribute tags.
For an introduction to the metadata component, please refer to the section: Metadata
III. Common Protocol Tags
The attribute tags in input and output structs fully support the OpenAPIv3 protocol. Once the corresponding protocol tags are added, the generated OpenAPIv3 information will automatically include the attribute.
Most tag attributes are automatically generated by the Server component, and there are not many tags that developers need to set manually.
1. Basic Tags
Commonly used basic tags include:
| Common OpenAPIv3 Tags | Description | Remarks |
|---|---|---|
path | Combined with the prefix at registration to form the API URI path | Used for g.Meta to mark API metadata |
tags | The tag to which the API belongs for API classification | Used for g.Meta to mark API metadata |
method | The request method for the API: GET/PUT/POST/DELETE...(case insensitive) | Used for g.Meta to mark API metadata |
deprecated | Marks the API as deprecated | Used for g.Meta to mark API metadata |
summary | Brief description of the API/parameter | Abbreviation sm |
description | Detailed description of the API/parameter | Abbreviation dc |
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 |
For more tags, please refer to the standard OpenAPIv3 protocol: https://swagger.io/specification/
2. 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:
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"
)
type GetListReq struct {
g.Meta `path:"/user" tags:"User" method:"get" x-group:"User/Info" summary:"Get user list with basic info."`
Page int `dc:"Page number" d:"1" x-sort:"1"`
Size int `dc:"Size for per page." d:"10" x-sort:"2"`
}
type GetListRes struct{}
type Controller struct{}
func (c *Controller) GetList(ctx context.Context, req *GetListReq) (res *GetListRes, err error) {
return nil, gerror.NewCode(gcode.CodeNotImplemented)
}
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()
}
After execution, visit the address http://127.0.0.1:8199/swagger to view the swagger ui, and visit http://127.0.0.1:8199/api.json to view the corresponding OpenAPIv3 documentation. The generated OpenAPIv3 documentation is as follows:
{
"openapi": "3.0.0",
"components": {
"schemas": {
"main.GetListReq": {
"properties": {
"Page": {
"default": 1,
"description": "Page number",
"format": "int",
"properties": {},
"type": "integer",
"x-sort": "1"
},
"Size": {
"default": 10,
"description": "Size for per page.",
"format": "int",
"properties": {},
"type": "integer",
"x-sort": "2"
}
},
"type": "object",
"x-group": "User/Info"
},
"main.GetListRes": {
"properties": {},
"type": "object"
}
}
},
"info": {
"title": "",
"version": ""
},
"paths": {
"/user": {
"get": {
"parameters": [
{
"description": "Page number",
"in": "query",
"name": "Page",
"schema": {
"default": 1,
"description": "Page number",
"format": "int",
"properties": {},
"type": "integer",
"x-sort": "1"
},
"x-sort": "1"
},
{
"description": "Size for per page.",
"in": "query",
"name": "Size",
"schema": {
"default": 10,
"description": "Size for per page.",
"format": "int",
"properties": {},
"type": "integer",
"x-sort": "2"
},
"x-sort": "2"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/main.GetListRes"
}
}
},
"description": ""
}
},
"summary": "Get user list with basic info.",
"tags": [
"User"
],
"x-group": "User/Info"
},
"x-group": "User/Info"
}
}
}
As you can see, the extension tags have been included in the API documentation.
IV. Expanding OpenAPIv3 Information
The core API information has already been automatically generated. If developers want to further complete the API information, they can obtain the OpenAPIv3 struct object via s.GetOpenApi() and manually fill in the corresponding attribute content. Let's look at an example where we design a common data structure around each API:
From this, we can see that with the general OpenAPIv3 object, we can customize its content and generate various other types of custom API documentation based on it.