前言

當開發RESTful API時，有效的文檔是極其重要的，它可以幫助開發者快速理解和使用API。Swagger是一個強大的工具，用於自動生成和維護API文檔。

本文將指導你如何使用Swagger在Gin框架中自動生成API文檔，並提供一些維護的最佳實踐。

為什麼選擇Swagger？

1.標準化: Swagger遵循OpenAPI規範，這是一個業界標準。
2.交互性: Swagger UI允許用戶直接從文檔中測試API，無需其他工具。

安裝流程

安裝必要的套件
首先，我們需要安裝swag CLI工具和Gin的Swagger中間件。

swagger cmd: 用於生成介面文件的命令列工具。

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

Starting in Go 1.17, installing executables with go get is deprecated. go install may be used instead:

1	go install github.com/swaggo/swag/cmd/swag@latest

gin-swagger: gin與swagger的中介軟體。
files: 幫助建立檔案

1 2	go get -u github.com/swaggo/gin-swagger go get -u github.com/swaggo/files

在你的主要應用文件中執行以下命令：

swag init

這邊實作遇到這個問題，後來看這篇文章
[Golang] “swag: command not found”error handling

參考這個解法

輸入以下指令以獲得 Go 的工作路徑
go env GOPATH

找路徑後到 go/bin資料夾中，輸入下方command

1	PATH=$(go env GOPATH)/bin:$PATH

回到專案資料夾，即可正常使用

這將生成docs目錄，其中包含Swagger的文檔資料。

將Swagger UI加入Gin
在你的Gin應用中，導入必要的包並將Swagger中間件添加到路由。

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

func main() {
    r := gin.Default()
    docs.SwaggerInfo.BasePath = "/api/v1"
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    // other routes...
    r.Run()
}

這一步實作發現還要引入專案 docs 文件才行

Swagger 註解

一般說明

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

// @contact.name nathan.lu
// @contact.url https://tedmax100.github.io/

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

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

API Info

註解	描述
title	必須簡單API專案的標題或主要的業務功能
version	必須目前這專案/API的版本
description	簡單描述
tersOfService	服務條款
contact.name	作者名稱
contact.url	作者blog
contact.email	作者email
license.name	必須許可證名稱
license.url	許可證網址
host	服務名稱或者是ip
BasePath	基本URL路徑, (/api/v1, /v2…)
schemes	提供的協定, (http, https)

API 功能註解

API Operation

helloHandler.go

// @Summary 說Hello
// @Id 1
// @Tags Hello
// @version 1.0
// @produce text/plain
// @Success 200 string string 成功後返回的值
// @Router /hello [get]
func GetHello(ctx *gin.Context) {...}

// @Summary Delete Hello
// @Id 1
// @Tags Hello
// @version 1.0
// @produce text/plain
// @param id path int true "id"
// @Success 200 string string 成功後返回的值
// @Router /hello/{id} [delete]
func DeleteHello(ctx *gin.Context) { ... }

註解	描述
summary	描述該API
tags	歸屬同一類的API的tag
accept	request的context-type
produce	response的context-type
param	參數按照參數名參數類型參數的資料類型是否必須註解 (中間都要空一格)
header	response header return code 參數類型資料類型註解
router	path httpMethod