山西企业建站方案,建设部网站官网造价工程师孙思新,西安建筑工程有限公司,wordpress 插件不生效1. 简介
Gin是Golang目前最为常用的Web框架之一。 公司项目验收需要API接口设计说明书#xff08;Golang后端服务基于Gin框架编写#xff09;#xff0c;编写任务自然就落到了我们研发人员身上。 项目经理提供了文档模板#xff0c;让我们参考模板来手动编写#xff0c;要…1. 简介
Gin是Golang目前最为常用的Web框架之一。 公司项目验收需要API接口设计说明书Golang后端服务基于Gin框架编写编写任务自然就落到了我们研发人员身上。 项目经理提供了文档模板让我们参考模板来手动编写要求两天内完成时间紧任务重。
看了下文档中API接口设计内容很简单但是接口数量太多还需要调整文档格式手动编写两天肯定搞不定。 发现API接口设计内容和swagger文档格式很相近那能不能使用工具生成swagger文档后再转换为word格式呢
和项目经理沟通了我的想法项目经理回答说内容丰富、格式统一就行不要求完全参考模板中的格式来。 既然这样那就开干吧
2. 生成swagger.json文档
本章节仅为演示操作步骤编写得很简洁。如果需要进一步的了解请查阅【4. 参考资料】章节
2.1. 安装swag
首先需要安装swag命令行工具go install github.com/swaggo/swag/cmd/swaglatest。
2.2. 新建示例项目
比如新建swagdoc项目go mod init swagedoc。
2.3. 新建main.go文件并输入示例代码
package mainimport (net/httpswagdoc/docsgithub.com/gin-gonic/ginswaggerfiles github.com/swaggo/filesginSwagger github.com/swaggo/gin-swagger
)// BasePath /api/v1// PingExample godoc
// Summary ping example
// Schemes
// Description do ping
// Tags example
// Accept json
// Produce json
// Success 200 {string} Helloworld
// Router /example/helloworld [get]
func Helloworld(g *gin.Context) {g.JSON(http.StatusOK, helloworld)
}func main() {r : gin.Default()docs.SwaggerInfo.BasePath /api/v1v1 : r.Group(/api/v1){eg : v1.Group(/example){eg.GET(/helloworld, Helloworld)}}r.GET(/swagger/*any, ginSwagger.WrapHandler(swaggerfiles.Handler))r.Run(:8080)
}2.4. 生成swagger.json文档
执行命令swagger init命令生成swagger.json文档。文件目录结构如下图所示 2.5. 访问api文档
执行下列命令运行示例程序
go mod tidy
go run ./main.go在浏览器中访问 api文档 可以通过浏览器直接访问api 3. 常见问题
3.1. Error parsing type definition报错如何解决
若出现解析类型定义的错误需要在执行swage init时加上对应的选项 例如swag init --parseDependency --parseInternal
3.2. 如何编写api注释
参考 声明式注释格式。
4. 将swagger.json文档转换为word文档
可以使用 swagger转word文档在线工具 来进行转换。
如果在线工具不能使用可以自行参考网上教程在本地搭建转换工具来进行转换就不在此赘述了。
转换后的word文档效果图如下所示
5. 参考资料
如何使用Swag将Go的注释转换为Swagger文档
源码示例
