golang學習之go web開發Swagger架構

Swagger是一個接口文檔生成工具

文章目錄

• 一、Swagger安裝
• 二、接口注解
• 三、main函數注解
• 四、文檔生成

一、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