Background

在前後端分离的专案维护一份完整且及时更新的api文件会极大的提高我们的工作效率，传统专案中介面文件都是由後端开发手写的，这种文件很难保证及时性，久而久之便失去了参考意义。swagger给我们提供了一种新的维护文件的方式，在gin中只需要编写一些注释即可生成一份可互动的介面文件。

What is Swagger?

Swagger 是由一间名为SmartBear Software 的公司，开发出来REST API 的工具，主要用来设计、构建、记录和使用REST API，使其可读性及可用性更佳，後来贡献给OpenAPI Initiative，并公开让所有人使用，它也是目前广泛使用在Web Backend的一套REST API测试工具。

Library

• swagger cmd: 用於生成介面文件的命令列工具。
• gin-swagger: gin与swagger的中介软件。
• template: 帮助建立swagger template

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/alecthomas/template

Init swagger files

使用swag init 来建立swagger初始档案，他会在你project下产生一个docs的folder，docs内则有docs.go, swagger.json and swagger.yaml三个档案

swag init

Init Swagger application

ginSwagger.URL主要是对应到swagger的template file

ginSwagger.WrapHandler则会是绑定swagger的路径

import (
			ginSwagger "github.com/swaggo/gin-swagger"
			"github.com/swaggo/gin-swagger/swaggerFiles"
)

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

Coding with Swagger

example的url为http://localhost:8080/swagger/index.html#

main

在main function上的annotation，主要会对应到 Swagger介面的title与description。

// @title Gin swagger
// @version 1.0
// @description Gin swagger

// @contact.name Flynn Sun

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

// @host localhost:8080
// schemes http
func main() {

我们可以从annotation对照实际画面所对应到的field or value

controller

在controller的annotation则是会对应到API

// GetUser GetUser @Summary
// @Tags user
// @version 1.0
// @produce application/json
// @param id path int true "id" default(1)
// @Success 200 string string successful return data
// @Router /v1/users/{id} [get]
func (u UsersController) GetUser(c *gin.Context) {
	id := c.Params.ByName("id")

	userId, err := strconv.ParseInt(id, 10, 64)
	if err != nil {
		c.JSON(http.StatusBadRequest, gin.H{
			"status": -1,
			"msg":    "Failed to parse params" + err.Error(),
			"data":   nil,
		})
	}

	userOne, err := service.SelectOneUsers(userId)
	if err != nil {
		c.JSON(http.StatusNotFound, gin.H{
			"status": -1,
			"msg":    "User not found" + err.Error(),
			"data":   nil,
		})
	} else {
		c.JSON(http.StatusOK, gin.H{
			"status": 0,
			"msg":    "Successfully get user data",
			"user":   &userOne,
		})
	}
}

我们可以从annotation对照实际画面所对应到的field or value

router

import _ "ironman-2021/docs"

记得要import docs进来，swagger indexl页面才能吃到该文档，否则会出现internal error

Complete with swag init

如果对swagger相关设定有做修正的话，务必在执行一次swag init 让他将修改的annotation给转移到swag template上，这样才会生效。

Summary

完成swagger之後，以後再开发API就可以产生标准且清晰的文献，并且以後测试时不需再借用像是POSTMAN的程序来辅助(高并发例外)，这次的程序码也会放在以下连结提供参考

https://github.com/Neskem/Ironman-2021/tree/Day-19