gin-swagger生成API文档

1. 导包

   ​ go get -u github.com/swaggo/swag/cmd/swag

2. 在main.go上加入主注释

   // @title 希科志愿者项目
   // @version 1.0
   // @description 希科志愿者项目接口文档// @host 8083
   // @BasePath /api/v1
   

3. 在接口对应的func上加入api注释

   // Create
   // @Summary 创建召回
   // @Tags 召回
   // @accept json
   // @Param ProjectNo body string true "项目编号"
   // @Param Title body string true "签到名称"
   // @Param TimeStart body alc_types.Time true "开始时间"
   // @Param TimeEnd body alc_types.Time true "结束时间"
   // @Param Duration body int true "召回时长"
   // @Param RemindUser body int true "提前n分钟，提醒志愿者"
   // @Param RemindManage body int true "提前n分钟，提醒管理员"
   // @Router /api/v1/manage/admin/create [post]
   func (ctrl *CallbackCtrl) Create(ctx *gin.Context) 
   

   这里有个点要注意:

   • @Param这个参数有固定的格式:

     param name`,`param type`,`data type`,`is mandatory?`,`comment` `attribute(optional)
     

     前面四个属性是必填的,分别对应:参数名,参数接收类型,参数数据类型,是否必须,注释

4. 生成swagger docs文件,这里有两种情况:

   1. main.go所在目录是文件根目录,直接在根目录运行:

      swag init即可在根目录生成docs文件夹

   2. main.go所在目录不是文件根目录,这个时候需要让swagger扫描到controller层的注释,但是命令还是必须在根目录下运行:

      swag init -g /cmd/ck_vol_server/main.go根据当前目录找到main.go所在位置

   3. 检查是否扫描成功,看生成的swagger.json文件中paths节点是否生成完成:

      {"swagger": "2.0","info": {"description": "希科志愿者项目接口文档","title": "希科志愿者项目","contact": {},"version": "1.0"},"host": "8083","basePath": "/api/v1","paths": {"/api/v1/manage/admin/Page": {"post": {"consumes": ["application/json"],"tags": ["召回"],"summary": "召回列表","parameters": [{"description": "页码","name": "PageNum","in": "body","required": true,"schema": {"type": "integer"}},{"description": "页数","name": "PageSize","in": "body","required": true,"schema": {"type": "integer"}}]}},"/api/v1/manage/admin/create": {"post": {"consumes": ["application/json"],"tags": ["召回"],"summary": "创建召回","parameters": [{"description": "项目编号","name": "ProjectNo","in": "body","required": true,"schema": {"type": "string"}},{"description": "签到名称","name": "Title","in": "body","required": true,"schema": {"type": "string"}},{"description": "开始时间","name": "TimeStart","in": "body","required": true,"schema": {"type": "string"}},{"description": "结束时间","name": "TimeEnd","in": "body","required": true,"schema": {"type": "string"}},{"description": "召回时长","name": "Duration","in": "body","required": true,"schema": {"type": "integer"}},{"description": "提前n分钟，提醒志愿者","name": "RemindUser","in": "body","required": true,"schema": {"type": "integer"}},{"description": "提前n分钟，提醒管理员","name": "RemindManage","in": "body","required": true,"schema": {"type": "integer"}}]}}}
      }
      

5. 注入swagger访问路径:

   // 添加swagger路由
   // 文档界面访问URL
   // http://127.0.0.1:8083/swagger/index.html
   r := gin.New()
   r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
   

   这里有个坑,除了要导入gin-swagger的两个包以外,还要导入生成的docs文件夹,否则访问swagger页面会报错:

   import (_ "ck-vol-server/docs"ginSwagger "github.com/swaggo/gin-swagger""github.com/swaggo/gin-swagger/swaggerFiles"
   )
   

6. 访问swagger页面:

   http://localhost:8083/swagger/index.html

本文来自互联网用户投稿，文章观点仅代表作者本人，不代表本站立场，不承担相关法律责任。如若转载，请注明出处。 如若内容造成侵权/违法违规/事实不符，请点击【内容举报】进行投诉反馈！