Go Web 框架 Gin 实践8—为它加上Swagger，帅帅的文档

2019-07-18 02:27发布

站内文章 / 后端开发

18 0

女 | 书童

私信

"\u003Cdiv\u003E\u003Cblockquote\u003E\u003Cp\u003EGo语言中文网，致力于每日分享编码知识，欢迎关注我，会有意想不到的收获！\u003C\u002Fp\u003E\u003C\u002Fblockquote\u003E\u003Cdiv class=\"pgc-img\"\u003E\u003Cimg src=\"http:\u002F\u002Fp1.pstatp.com\u002Flarge\u002Fdfic-imagehandler\u002F6cbed57c-b663-400f-85b6-e0c8807b215f\" img_width=\"1023\" img_height=\"682\" alt=\"Go Web 框架 Gin 实践8—为它加上Swagger，帅帅的文档\" inline=\"0\"\u003E\u003Cp class=\"pgc-img-caption\"\u003E\u003C\u002Fp\u003E\u003C\u002Fdiv\u003E\u003Cp\u003E一个好的 API's，必然离不开一个好的API文档\u003C\u002Fp\u003E\u003Cp\u003E要开发纯手写 API 文档，不存在的 :=)\u003C\u002Fp\u003E\u003Cp\u003E项目地址：https:\u002F\u002Fgithub.com\u002FEDDYCJY\u002Fgo-gin-example\u003C\u002Fp\u003E\u003Ch1\u003E安装 swag\u003C\u002Fh1\u003E\u003Cp\u003E\u003Cstrong\u003E1、go get\u003C\u002Fstrong\u003E\u003C\u002Fp\u003E\u003Cpre\u003E$ go get -u github.com\u002Fswaggo\u002Fswag\u002Fcmd\u002Fswag\u003Cbr\u003E\u003C\u002Fpre\u003E\u003Cp\u003E若 $GOPATH\u002Fbin 没有加入$PATH中，你需要执行将其可执行文件移动到$GOBIN下\u003C\u002Fp\u003E\u003Cpre\u003Emv $GOPATH\u002Fbin\u002Fswag \u002Fusr\u002Flocal\u002Fgo\u002Fbin\u003Cbr\u003E\u003C\u002Fpre\u003E\u003Cp\u003E\u003Cstrong\u003E2、gopm get\u003C\u002Fstrong\u003E\u003C\u002Fp\u003E\u003Cp\u003E该包有引用golang.org上的包，若无科学上网，你可以使用 gopm 进行安装\u003C\u002Fp\u003E\u003Cpre\u003Egopm get -g -v github.com\u002Fswaggo\u002Fswag\u002Fcmd\u002Fswag\u003Cbr\u003Ecd $GOPATH\u002Fsrc\u002Fgithub.com\u002Fswaggo\u002Fswag\u002Fcmd\u002Fswag\u003Cbr\u003Ego install\u003Cbr\u003E\u003C\u002Fpre\u003E\u003Cp\u003E同理将其可执行文件移动到$GOBIN下\u003C\u002Fp\u003E\u003Ch1\u003E验证是否安装成功\u003C\u002Fh1\u003E\u003Cpre\u003E$ swag -v\u003Cbr\u003Eswag version v1.1.1\u003Cbr\u003E\u003C\u002Fpre\u003E\u003Ch1\u003E安装 gin-swagger\u003C\u002Fh1\u003E\u003Cpre\u003E$ go get -u github.com\u002Fswaggo\u002Fgin-swagger\u003Cbr\u003E$ go get -u github.com\u002Fswaggo\u002Fgin-swagger\u002FswaggerFiles\u003Cbr\u003E\u003C\u002Fpre\u003E\u003Cp\u003E注：三个包都有一定大小，安装需要等一会或要科学上网\u003C\u002Fp\u003E\u003Cdiv class=\"pgc-img\"\u003E\u003Cimg src=\"http:\u002F\u002Fp1.pstatp.com\u002Flarge\u002Fdfic-imagehandler\u002F066c88bb-6208-48c8-b5c4-42f72d4191f9\" img_width=\"1023\" img_height=\"466\" alt=\"Go Web 框架 Gin 实践8—为它加上Swagger，帅帅的文档\" inline=\"0\"\u003E\u003Cp class=\"pgc-img-caption\"\u003E\u003C\u002Fp\u003E\u003C\u002Fdiv\u003E\u003Ch1\u003E初始化\u003C\u002Fh1\u003E\u003Cp\u003E\u003Cstrong\u003E编写API注释\u003C\u002Fstrong\u003E\u003C\u002Fp\u003E\u003Cp\u003ESwagger 中需要将相应的注释或注解编写到方法上，再利用生成器自动生成说明文件\u003C\u002Fp\u003E\u003Cp\u003Egin-swagger 给出的范例：\u003C\u002Fp\u003E\u003Cpre\u003E\u002F\u002F @Summary Add a new pet to the store\u003Cbr\u003E\u002F\u002F @Description get string by ID\u003Cbr\u003E\u002F\u002F @Accept json\u003Cbr\u003E\u002F\u002F @Produce json\u003Cbr\u003E\u002F\u002F @Param some_id path int true \"Some ID\"\u003Cbr\u003E\u002F\u002F @Success 200 {string} string\t\"ok\"\u003Cbr\u003E\u002F\u002F @Failure 400 {object} web.APIError \"We need ID!!\"\u003Cbr\u003E\u002F\u002F @Failure 404 {object} web.APIError \"Can not find ID\"\u003Cbr\u003E\u002F\u002F @Router \u002Ftestapi\u002Fget-string-by-int\u002F{some_id} [get]\u003Cbr\u003E\u003C\u002Fpre\u003E\u003Cp\u003E我们可以参照 Swagger 的注解规范和范例去编写\u003C\u002Fp\u003E\u003Cpre\u003E\u002F\u002F @Summary 新增文章标签\u003Cbr\u003E\u002F\u002F @Produce json\u003Cbr\u003E\u002F\u002F @Param name query string true \"Name\"\u003Cbr\u003E\u002F\u002F @Param state query int false \"State\"\u003Cbr\u003E\u002F\u002F @Param created_by query int false \"CreatedBy\"\u003Cbr\u003E\u002F\u002F @Success 200 {string} json \"{\"code\":200,\"data\":{},\"msg\":\"ok\"}\"\u003Cbr\u003E\u002F\u002F @Router \u002Fapi\u002Fv1\u002Ftags [post]\u003Cbr\u003Efunc AddTag(c *gin.Context) {\u003Cbr\u003E\u002F\u002F @Summary 修改文章标签\u003Cbr\u003E\u002F\u002F @Produce json\u003Cbr\u003E\u002F\u002F @Param id path int true \"ID\"\u003Cbr\u003E\u002F\u002F @Param name query string true \"ID\"\u003Cbr\u003E\u002F\u002F @Param state query int false \"State\"\u003Cbr\u003E\u002F\u002F @Param modified_by query string true \"ModifiedBy\"\u003Cbr\u003E\u002F\u002F @Success 200 {string} json \"{\"code\":200,\"data\":{},\"msg\":\"ok\"}\"\u003Cbr\u003E\u002F\u002F @Router \u002Fapi\u002Fv1\u002Ftags\u002F{id} [put]\u003Cbr\u003Efunc EditTag(c *gin.Context) {\u003Cbr\u003E\u003C\u002Fpre\u003E\u003Cp\u003E详细的注解请参见 go-gin-example。以确保获取最新的 swag 语法\u003C\u002Fp\u003E\u003Ch1\u003E生成\u003C\u002Fh1\u003E\u003Cp\u003E我们进入到gin-blog的项目根目录中，执行初始化命令\u003C\u002Fp\u003E\u003Cpre\u003E[$ gin-blog]# swag init\u003Cbr\u003E2018\u002F03\u002F13 23:32:10 Generate swagger docs....\u003Cbr\u003E2018\u002F03\u002F13 23:32:10 Generate general API Info\u003Cbr\u003E2018\u002F03\u002F13 23:32:10 create docs.go at docs\u002Fdocs.go\u003Cbr\u003E\u003C\u002Fpre\u003E\u003Cp\u003E完毕后会在项目根目录下生成docs\u003C\u002Fp\u003E\u003Cp\u003Edocs\u002F\u003C\u002Fp\u003E\u003Cp\u003E├── docs.go\u003C\u002Fp\u003E\u003Cp\u003E└── swagger\u003C\u002Fp\u003E\u003Cp\u003E ├── swagger.json\u003C\u002Fp\u003E\u003Cp\u003E └── swagger.yaml\u003C\u002Fp\u003E\u003Cp\u003E我们可以检查 docs.go 文件中的 doc 变量，详细记载中我们文件中所编写的注解和说明 \u003C\u002Fp\u003E\u003Cdiv class=\"pgc-img\"\u003E\u003Cimg src=\"http:\u002F\u002Fp1.pstatp.com\u002Flarge\u002Fpgc-image\u002F781f11bcf9004774ac3b40e6ccf8df19\" img_width=\"531\" img_height=\"697\" alt=\"Go Web 框架 Gin 实践8—为它加上Swagger，帅帅的文档\" inline=\"0\"\u003E\u003Cp class=\"pgc-img-caption\"\u003E\u003C\u002Fp\u003E\u003C\u002Fdiv\u003E\u003Ch1\u003E验证\u003C\u002Fh1\u003E\u003Cp\u003E大功告成，访问一下 http:\u002F\u002F127.0.0.1:8000\u002Fswagger\u002Findex.html，查看 API 文档生成是否正确。是不是很帅？\u003C\u002Fp\u003E\u003Cdiv class=\"pgc-img\"\u003E\u003Cimg src=\"http:\u002F\u002Fp1.pstatp.com\u002Flarge\u002Fpgc-image\u002F82587e4ff9f94082a98b37ed04bbee16\" img_width=\"800\" img_height=\"500\" alt=\"Go Web 框架 Gin 实践8—为它加上Swagger，帅帅的文档\" inline=\"0\"\u003E\u003Cp class=\"pgc-img-caption\"\u003E\u003C\u002Fp\u003E\u003C\u002Fdiv\u003E\u003Ch1\u003E参考\u003C\u002Fh1\u003E\u003Cp\u003E本系列示例代码\u003C\u002Fp\u003E\u003Cul\u003E\u003Cli\u003Ego-gin-example\u003C\u002Fli\u003E\u003C\u002Ful\u003E\u003Cblockquote\u003E\u003Cp\u003E本系列作者：煎鱼，原创授权发布\u003C\u002Fp\u003E\u003C\u002Fblockquote\u003E\u003C\u002Fdiv\u003E"

文章来源: https://www.toutiao.com/group/6706456712292860424/