golang学习之go web开发Swagger框架

Swagger是一个接口文档生成工具

一、Swagger安装

go get github.com/gin-gonic/gin
go get github.com/swaggo/files
go get github.com/swaggo/gin-swagger

go install github.com/swaggo/gin-swagger

二、接口注解

@Summary 摘要
@Produce API可以产生的MIME类型列表。如JSON、XML、HTML等
@Param 参数格式，依次为：参数名、参数类型、数据类型、是否必填、注释
@Success 响应成功，依次为：状态码、参数类型、数据类型、注释
@Failure 响应失败，依次为：状态码、参数类型、数据类型、注释
@Router 路由，依次为：路由路径、httpMethod

package user

import "github.com/gin-gonic/gin"

// @Summary 查询用户
// @Produce json
// @Param userName query string false "用户名" maxlength(20)
// @Param userCode query string false "用户代码" maxlength(20)
// @Param page query int true "查询页"
// @Param pageSize query int true "每页数量"
// @Success 200 {object} user.User "成功"
// @Failure 500 {object} error "内部错误"
// @Router /api/v1/user [post]
func List(c *gin.Context) {
    
    

}

三、main函数注解

package main

import (
	_ "fa.com/wms/docs"
	"fa.com/wms/domain/user"
	"github.com/gin-gonic/gin"
	swaggerFiles "github.com/swaggo/files"
	ginSwagger "github.com/swaggo/gin-swagger"
)

// @title 仓储物流系统
// @version 1.0
// @description go实现仓储物流系统
// @termsOfService https://blog.csdn.net/weixin_56349119?type=blog
func main() {
    
    
	r := gin.New()
	r.Use(gin.Logger())
	r.Use(gin.Recovery())

	r.POST("/api/v1/user", user.List)

	url := ginSwagger.URL("http:localhost:8000/swagger/doc.json")
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

	r.Run()
}

四、文档生成

项目根目录下执行swag init 命令

swag init 

生成docs目录、docs.go、swagger.json、swagger.yaml

访问 http://localhost:8080/swagger/index.html