Swagger与go-zero框架生成和展示API文档详解
在现代API开发中，清晰、准确的接口文档是前后端协作的重要基础。作为一款功能强大的Go语言微服务框架，go-zero提供了简便的方式来生成Swagger文档，极大地提高了API开发的效率与质量。今天，我们将深入探讨Swagger的作用以及如何通过goctl工具快速生成Swagger文档。
Swagger简介
API文档的行业标准，Swagger是一个开源的API文档规范和工具集。它可以帮助开发者设计、构建、文档化和使用RESTful API。作为OpenAPI规范的前身，Swagger已经成为行业标准，被广泛应用于各类项目中。
Swagger的主要优势
- 标准化文档：提供结构化的API文档，使API易于理解和使用。
- 交互式体验：自带UI界面，可以直接在浏览器中测试API。
- 代码生成：支持从文档生成客户端和服务端代码。
- 版本控制：方便API的版本管理和迭代。
- 减少沟通成本：前后端开发人员可以基于同一份文档协作。
go-zero中的Swagger支持
go-zero框架通过goctl工具提供了Swagger文档的生成功能，可以基于API文件自动生成JSON和YAML格式的Swagger文档。这使得开发者可以专注于业务逻辑的开发，而将API文档的生成工作交给工具自动完成。
温馨提示
- Swagger功能目前处于实验性阶段。
- 要求：goctl 版本大于1.8.2。
- 需要开启实验性功能：
goctl env -w GOCTL_EXPERIMENTAL=on。
在API文件中定义Swagger信息
go-zero使用自定义的API语法来定义服务接口，同时支持在API文件中添加Swagger相关的元数据。以下是一个示例：
syntax = "v1"info (title: "演示 API" // 对应 swagger 的 titledescription: "演示 api 生成 swagger 文件的 api 完整写法" // 对应 swagger 的 descriptionversion: "v1" // 对应 swagger 的 versiontermsOfService: "https://github.com/zeromicro/go-zero" // 对应 swagger 的 termsOfServicecontactName: "keson.an" // 对应 swagger 的 contactNamecontactURL: "https://github.com/zeromicro/go-zero" // 对应 swagger 的 contactURLcontactEmail: "example@gmail.com" // 对应 swagger 的 contactEmaillicenseName: "MIT" // 对应 swagger 的 licenseNamelicenseURL: "https://github.com/zeromicro/go-zero" // 对应 swagger 的 licenseURLconsumes: "application/json" // 对应 swagger 的 consumes，不填默认为 application/jsonproduces: "application/json" // 对应 swagger 的 produces，不填默认为 application/jsonschemes: "https" // 对应 swagger 的 schemes，不填默认为 httpshost: "example.com" // 对应 swagger 的 host，不填默认为 127.0.0.1basePath: "/v1" // 对应 swagger 的 basePath，不填默认为 /wrapCodeMsg: "true" // 是否用 code-msg 通用响应体，如果开启，则以格式 {"code":0,"msg":"OK","data":$data} 包括响应体bizCodeEnumDescription: "1001-未登录<br>1002-无权限操作" // 业务错误码枚举描述
)type (QueryReq { Id int `form:"id,range=[1:10000],example=10"` Name string `form:"name,example=keson.an"` Avatar string `form:"avatar,optional,example=https://example.com/avatar.png"` }QueryResp { Id int `json:"id,example=10"` Name string `json:"name,example=keson.an"` }
)@server (tags: "query 演示" // 对应 swagger 的 tagssummary: "query 类型接口集合" // 对应 swagger 的 summary
) service Swagger { @doc (description: "query 接口") @handler queryget /query (QueryReq) returns (QueryResp)@doc (description: "query path 中包含 id 字段接口") @handler queryPathget /query/:id (PathQueryReq) returns (PathQueryResp)
}
goctl swagger 命令的使用方法
goctl swagger 是go-zero提供的命令行工具，用于根据API文件生成Swagger文档。以下是其基本用法：
生成Swagger文档
# 基本用法
goctl api swagger --api <api文件路径> --dir <输出目录># 示例
goctl api swagger --api example.api --dir ./docs/swagger
常用参数说明
--api：指定API文件的路径。--dir：指定生成的Swagger文档的输出目录。
Swagger文档的使用
生成Swagger文档后，可以通过多种方式进行查看和使用：
使用Swagger UI
-
准备Swagger JSON文件：确保你有一个有效的Swagger/OpenAPI规范的JSON文件。这个文件通常命名为
swagger.json或openapi.json，并放置在你的web服务器的可访问目录下。例如，文件路径可能是http://yourdomain.com/api/swagger.json。 -
下载并部署Swagger UI：Swagger UI是一个开源项目，可以直接从GitHub页面下载或者通过npm安装。下载后，将Swagger UI的静态文件部署到你的web服务器上。这些文件通常包括一个HTML文件（如
index.html）和其他必要的CSS、JS资源。 -
配置Swagger UI：打开Swagger UI的
index.html文件，找到如下配置部分：<!-- 在这里配置Swagger UI --> <script> window.onload = function() {// 初始化Swagger UISwaggerUIBundle({url: "https://petstore.swagger.io/v2/swagger.json", // 修改为你的Swagger JSON文件URLdom_id: '#swagger-ui',presets: [SwaggerUIBundle.presets.apis,SwaggerUIStandalonePreset],layout: "BaseLayout",deepLinking: true,showExtensions: true,showCommonExtensions: true}) } </script>将
url属性的值替换为你第一步中准备好的Swagger JSON文件的实际URL。 -
访问Swagger UI：部署好Swagger UI及其依赖资源后，通过浏览器访问Swagger UI的入口页面（通常是
index.html），你就可以看到根据JSON文件生成的API文档界面了。你可以浏览API、阅读描述、尝试调用等。
这种方法适用于那些不想或不能直接在代码中集成Swagger的情况，比如对已有API文档进行快速可视化展示，或者是对第三方API文档进行本地浏览和测试。
实际案例分析
让我们来看一个更复杂的例子，展示在实际项目中如何使用go-zero的Swagger功能：
type (JsonReq { Id int `json:"id,range=[1:10000],example=10"` Name string `json:"name,example=keson.an"` Avatar string `json:"avatar,optional"` Language string `json:"language,options=golang|java|python|typescript|rust"` Gender string `json:"gender,default=male,options=male|female,example=male"` }JsonResp { Id int `json:"id"` Name string `json:"name"` Avatar string `json:"avatar"` Language string `json:"language"` Gender string `json:"gender"` }
)@server (tags: "post json api 演示"summary: "json 请求类型接口集合"
) service Swagger { @doc (description: "简单的 json 请求体接口") @handler jsonSimplepost /json/simple (JsonReq) returns (JsonResp)
}
生成的Swagger文档将包含完整的请求和响应模型定义，包括参数范围、可选值等信息，这使得API的使用变得非常直观和简单。
最佳实践建议
在使用go-zero的Swagger功能时，以下是一些建议的最佳实践：
- 完善API描述：在API文件中提供详细的接口描述、参数说明和示例值。
- 合理分组：使用
@server标签对API进行逻辑分组，提高文档的可读性。 - 版本控制：为API定义明确的版本信息，方便管理API的迭代。
- 自动化集成：将Swagger文档的生成集成到CI/CD流程中，确保文档与代码的一致性。
- 参数校验：充分利用go-zero提供的参数校验功能，保证API的健壮性。
总结
go-zero框架通过goctl工具提供的Swagger支持，极大地简化了API文档的生成和维护工作。虽然目前该功能还处于实验阶段，但已经可以在实际项目中发挥重要作用。开发者只需在API文件中定义接口和数据模型，并开启实验性功能，就可以自动生成标准化的Swagger文档，无需额外的工作。
在微服务架构日益流行的今天，清晰的API文档对于系统的可维护性和开发效率至关重要。go-zero的Swagger支持为开发者提供了一个简单而强大的解决方案，值得在实际项目中应用。希望本文对你理解和使用go-zero的Swagger功能有所帮助！如有任何问题或建议，欢迎在评论区留言讨论。
使用示例
上面步骤成功生成了静态的json文件。接下来可以复制以下内容，将其保存为swagger-ui.html文件，然后放置在任一静态文件目录。比如static/swagger目录下。
<!DOCTYPE html>
<html>
<head><meta charset="utf-8"><title>Swagger UI</title><link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
</head>
<body><div id="swagger-ui"></div><script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script><script>window.onload = function() {const ui = SwaggerUIBundle({url: "./goNutpi.json",dom_id: '#swagger-ui'});};</script>
</body>
</html>
在go-zero项目的main.go中启用静态文件服务：
package mainimport ("flag""fmt""net/http""goNutpi/internal/config""goNutpi/internal/handler""goNutpi/internal/svc""github.com/zeromicro/go-zero/core/conf""github.com/zeromicro/go-zero/rest"
)var configFile = flag.String("f", "etc/gonutpi-api.yaml", "the config file")func main() {flag.Parse()var c config.Configconf.MustLoad(*configFile, &c)//启用静态文件服务，目录staticfs := http.Dir("./static")server := rest.MustNewServer(c.RestConf, rest.WithFileServer("/static/", fs))defer server.Stop()ctx := svc.NewServiceContext(c)handler.RegisterHandlers(server, ctx)fmt.Printf("Starting server at %s:%d...\n", c.Host, c.Port)server.Start()
}最后，启动服务。在浏览器中就可以访问啦。如：
http://120.27.146.247:7000/static/docs/swagger/swagger-ui.html
通过上述步骤，您可以基于静态Swagger JSON文件使用Swagger UI来展示和测试API，而不需要直接集成到代码中。这种方式非常适合文档和测试的需求，极大地提高了API开发的效率与质量。