This page looks best with JavaScript enabled

gin-swagger 自动化构建 API 文档

 ·  ☕ 2 min read · 👀... views

前后端的交互一般流程是这样的,后端暴露出 API 后,交给前端,前端根据 API 的响应,编写前端页面,一定程度上 API 是前后端的交互桥梁。

API 文档主要要包含:

  • 路由:包括路径参数、请求参数、还是请求体参数
  • 动作:HTTP 请求动作,GET、POST、DELETE、PUT
  • 响应:请求之后的返回值包含哪些信息,一般是 JSON

swagger 可以将代码和 api 文档维护在一起,通过访问服务进程的 swagger 页面就可以得到完善的 api 文档,还可以直接 Try out。

doc文档

做法

  1. 要知道 swagger 注释的语法
  2. 如何在 gin 内怎么使用

注释语法这个,全靠查文档。对着文档来。

当然我觉得最好的方法是什么呢,是模仿,找一个别人已经写好的,修修改改,看看能不能编译通过,编译通过后是不是你预期的结果。不是的话,继续修修改改,再编译,再看是不是你希望的结果。如此反复。

mark

1. 编写全局信息注释,在主函数上编写

格式:// @param info

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host 127.0.0.1:8080
// @BasePath /v1
func main() {
	r := gin.Default()
	r.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	r.GET("v1/hello/:name", Name)
	r.Run()
}
r.GET("/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

这个路由和响应需要有,路由随便的定义,但我觉得我这种方式一目了然,知道是文档。

其他注释对照着参考文档即可。

2. 编写应用注释

即在响应函数的上方编写注释

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Name will print hello name
// @Summary Print
// @Accept json
// @Tags Name
// @Security Bearer
// @Produce  json
// @Param name path string true "name"
// @Resource Name
// @Router /hello/{name} [get]
// @Success 200 {object} main.Message
func Name(c *gin.Context) {
	name := c.Param("name")

	if name == "" {
		return
	}
	var message Message

	message = Message{
		MessageInfo: fmt.Sprintf("hello %s", name),
	}
	c.JSON(http.StatusOK, message.Serializer())
}

这里最好把响应体统一成结构体的形式。即

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
type Message struct {
    MessageInfo string `json:"message"`
}

func (m *Message) Serializer()Message{
    return Message{
        MessageInfo: m.MessageInfo,
    }

}

3. 目录下 执行命令

1
swag init

自动生成 docs 文件夹,内含 swagger.json 、swagger.json 、 docs.go

编译不通过,查看报错信息,修改注释。

4. 导入生成的 docs 文件

1
2
3
4
5
6
7
8
9
import (
    "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"

    _ "./docs" // docs is generated by Swag CLI, you have to import it.
    "github.com/gin-gonic/gin"
    "net/http"
    "fmt"
)

即这个 ./docs

5. go run main.go

访问:http://127.0.0.1:8080/docs/index.html

即可查看 swagger 文档。

mark

Share on

睡沙发の沙皮狗
WRITTEN BY
睡沙发の沙皮狗
👨‍💻 Backend Developer/📚 Learner/🚀 Opensource enthusiast

 

What's on this Page