goctl-swag

🌍 简体中文 ∙ English
Swagger 2.0 文档

简介

本项目是基于go-zero写的一个插件，用于根据go-zero的api 生成swagger文档，目前只支持swagger2.0版本，另外添加了前端的页面增强部分， 使用了swagger-bootstrap作为前端页面部分的增强, 借鉴了goctl-swagger一部分思路和代码， 使用了go-openapi作为swagger的解析和生成。

也正好借助这个项目对go-zero有了更深的了解（我刚接触go-zero不久）

目录

• 安装插件
• 快速开始
• 截图
• goctl-swag指令说明
• 格式说明
  • 通用API信息
  • API声明
  • API分组声明
  • Mime类型
  • 参数类型
  • 数据类型
• 聚合Api文档用法
• 感谢

安装插件

go install github.com/CloverOS/goctl-swag/cmd/goctl-swag@latest

快速开始

先安装好goctl（版本为1.5.4）以及goctl-swag插件

• 以testdata/go-zero/user.api为例,进行文档生成

git clone https://github.com/CloverOS/goctl-swag
cd goctl-swag

• 下载本项目后,接着执行以下指令

goctl api plugin -p goctl-swag="init" -api testdata/user.api -dir testdata/go-zero/user 

• 就会在testdata/go-zero/user/doc生成一个doc_gin.go文件，这个文件就是swagger文档的生成文件，里面包含了swagger的json数据和前端页面的增强部分的整合。

• 最后执行以下指令生成go-zero项目（可以参考goctl-插件指令）

goctl api go -api testdata/user.api -dir testdata/go-zero/user 

• 进行页面增强适配 修改test/data/go-zero/user/user.go如下，使用gin作为router（推荐）

func main() {
    flag.Parse()

    var c config.Config
    conf.MustLoad(*configFile, &c)

    r := gin.NewRouter()
    server := rest.MustNewServer(c.RestConf, rest.WithRouter(r))
    defer server.Stop()

    ctx := svc.NewServiceContext(c)
    handler.RegisterHandlers(server, ctx)
    //for gin-swagger-bootstrap doc
    server.AddRoute(rest.Route{
        Method:  http.MethodGet,
        Path:    "/swagger/*any",
        Handler: doc.WrapHandler(),
    })
    fmt.Printf("Starting server at %s:%d...\n", c.Host, c.Port)
    server.Start()
}

• 使用默认路由写法

server.AddRoutes([]rest.Route{
    {
        Method:  http.MethodGet,
        Path:    "/swagger",
        Handler: goctl_swag.Doc("/swagger", "dev"),
    },
    {
        Method: http.MethodGet,
        Path:   "/swagger-json",
        Handler: func (writer http.ResponseWriter, request *http.Request) {
            writer.Header().Set("Content-Type", "application/json; charset=utf-8")
            _, err := writer.Write([]byte(doc.Doc))
            if err != nil {
                httpx.Error(writer, err)
            }
        },
    },
})

• 最后启动项目，访问http://localhost:8888/swagger即可看到效果

go mod tidy
go run testdata/go-zero/user/user.go -f testdata/go-zero/user/etc/user.yaml 

截图

goctl-swag指令说明

goctl-swag init [command options] [arguments...]

参数	说明	默认值
--host	API请求地址	localhost:8888
--basepath, --bp	URL请求前缀	/
--dir, -d	生成的doc.go的文件夹路径	./doc
--webframe, --wb	选择使用哪个框架	gin
--cover, --cv	选择是否自动覆盖文件	true
--router, --rt	是否生成路由信息	true

格式说明

可以参考user.api

通用API信息

示例

info(
	title: "示例文档"
	desc: "文档描述"
	version: "1.0"
	basePath: "/v1"
	termsOfService: "[$https]swagger.io/terms/"
	contact_name: "khthink"
	contact_url: "[$https]khthink.cn"
	contact_email: "example"
	license_name: "Apache 2.0"
	license_url: "[$https]www.apache.org/licenses/LICENSE-2.0.html"
	BasePath: "/v1"
	accept: "json"
	produce: "json"
	schemes: "http,https"
	securityDefinitions_apikey: "AccessToken"
	in: "header"
	name: "Access-Token"
)

注释	说明
title	必填 应用程序的名称。
version	必填 提供应用程序API的版本。
description	应用程序的简短描述。
termsOfService	API的服务条款。
contact_name	公开的API的联系信息。
contact_url	联系信息的URL。 必须采用网址格式。
contact_email	联系人/组织的电子邮件地址。 必须采用电子邮件地址的格式。
license_name	必填 用于API的许可证名称。
license_url	用于API的许可证的URL。 必须采用网址格式。
host	运行API的主机（主机名或IP地址）。
BasePath	运行API的基本路径。
accept	API 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。
produce	API可以生成的MIME类型的列表。值必须如“Mime类型”中所述。
schemes	用,分隔的请求的传输协议。

关于无法使用"https://"类似的这种字符串的问题，可以使用[$https]这种方式来解决，会自动替换为https://。

[$https] ==> https://
[$http] ==> http://
[$ws] ==> ws://
[$wss] ==> wss://

API声明

@doc(
    summary: "登录"
    description: "客户端用户登录"
)
@handler jsonLoginHandler
post /users/login (JsonRequest) returns (TokenResponse)

或者简写

@doc "表单登录"
@handler formLoginHandler
post /users/form/login (FormRequest)

API分组声明

@server(
    group: login
    open: true
    prefix: /login
    tag: 登录模块
)

• open: true 代表该模块是否为开放接口，不写的话默认为私有接口（即false）

请求参数声明

Json

JsonRequest {
    RequestId string `header:"requestId"`       //请求id
    Account   string `json:"account"`           //账号
    Password  string `json:"password"`          //密码
    SecCode   string `json:"sec_code,optional"` //安全密码
}

文件上传

UploadRequest {
    MyFile string `form:"myFile,file"` //文件
}

Mime类型

swag 接受所有格式正确的MIME类型, 即使匹配 */*。除此之外，swag还接受某些MIME类型的别名，如下所示：

Alias	MIME Type
json	application/json
xml	text/xml
plain	text/plain
html	text/html
mpfd	multipart/form-data
x-www-form-urlencoded	application/x-www-form-urlencoded
json-api	application/vnd.api+json
json-stream	application/x-json-stream
octet-stream	application/octet-stream
png	image/png
jpeg	image/jpeg
gif	image/gif

参数类型

• query
• path
• header
• body
• formData

数据类型

• string (string)
• integer (int, uint, uint32, uint64)
• number (float32)
• boolean (bool)
• user defined struct

聚合Api文档用法

在生成的doc_gin.go中，有一个WrapHandlerWithGroupObject方法，可以将多个api文档聚合到一个文档中，用法如下：

doc.WrapHandlerWithGroupObject([]gen.SwaggerGroupObject{
    {
        Name:           "user",
        Url:            "../swagger/user.json",
        SwaggerVersion: "2.0",
        Location:       "",
    },
    {
        Name:           "order",
        Url:            "localhost:8889",
        SwaggerVersion: "2.0",
        Location:       "",
    },
})

• 这里url填写不同微服务的swag文档数据,之后就可以在页面的左上角中选择对应的微服务文档了

感谢

go-zero
goctl-swagger
go-openapi