> For the complete documentation index, see [llms.txt](https://minilabmemo.gitbook.io/golang-memo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://minilabmemo.gitbook.io/golang-memo/advance-application/gin-web-framework/ginswagger.md).

# GinSwagger

1. 先安裝工具 from . <https://github.com/swaggo/swag> &#x20;

```
根據指令1.16 or newer
go install github.com/swaggo/swag/cmd/swag@latest
....

確認下載工具成功
$ swag -v
swag version v1.8.6

可以查看對應指令
$ swag init --help  
```

2\.   根據gin-swagger說明 ，在main.go路徑 下swag init

see from  <https://github.com/swaggo/gin-swagger>

會產生

```
swag init
cmd/app-core/docs/docs.go
cmd/app-core/docs/swagger.json
cmd/app-core/docs/swagger.yaml
```

3\.   加入swagger 相關的註解或code

3-1 根據gin-swagger說明 ，在main.go 添加說明

<pre class="language-diff"><code class="lang-diff">import (

	"github.com/gin-gonic/gin"
<strong>+	_ "github.com/minilabmemo/go-rest-arch/cmd/app-core/docs"
</strong>	
)

加入註解
+// @title           Swagger Example API
+// @version         1.0
+// @description     This is a sample server celler server.
func main() {
	start := time.Now()
	errs := make(chan error, 3)
	listenForInterrupt(errs)
	startup(errs)
	defer stopMain()

	zap.S().Infof("Service started in: %v", time.Since(start))
	zap.S().Infof("Version %s", internal.Version)
	c := &#x3C;-errs
	zap.S().Warnf("terminating: %v", c)
}

或者


import (
+	docs "github.com/minilabmemo/go-rest-arch/cmd/app-core/docs"
)
func main() {
<strong>+	docs.SwaggerInfo.Title = fmt.Sprintf("Swagger %s API", config.ConfigData.Service.Name)
</strong>	}	
	
</code></pre>

3-2 在對應HttpServer啟動的地方加入swagger UI的路由

記得在對應的gomod  獲取相關的dependency

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

<pre class="language-diff"><code class="lang-diff">package apis

import (
	"fmt"

	"github.com/gin-gonic/gin"

	"github.com/minilabmemo/go-rest-arch/internal/config"
<strong>+	swaggerfiles "github.com/swaggo/files"
</strong>+	ginSwagger "github.com/swaggo/gin-swagger"
	"go.uber.org/zap"
)

func StartHttpServer(errChan chan error, engine *gin.Engine) {
+	engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerfiles.Handler))
	endpoint := fmt.Sprintf(":%d", config.ConfigData.Service.Port)
	go func() {
		errChan &#x3C;- engine.Run(endpoint)
	}()

	zap.S().Infof("Listening on port: %d", config.ConfigData.Service.Port)
}

</code></pre>

4\. 添加完之後再下一次swag init 啟動go run main.go

打開<http://localhost:8888/swagger/index.htm>l 就可以看到對應的swagger UI了

可是這時還沒有任何可以用的ＡＰＩ註解

5\. 添加對應的API Info路由註解

```
// @Summary Get info API
// @Schemes
// @Description Get info API
// @Tags infos
// @Accept json
// @Produce json
// @Success 200 {string} Helloworld
// @Router /service/api/v1/info [get]
func (a *InfoHandler) GetInfo(c *gin.Context) {
	//call usecase method
	info, _ := a.CUsecase.GetInfo()
	c.JSON(http.StatusOK, info)
}
```

添加完再下一次swag init --parseDependency 。

* 如果讀取的路由在不同dependency下可以這樣去抓到底層的註解

參考範例：[go-rest-arch/tree/feat-info-apis](https://github.com/minilabmemo/go-rest-arch/tree/feat-info-apis)<br>

#### 參考：

| reference                                                      | Memo.                                                                                                     |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| <h3></h3><p><https://github.com/swaggo/gin-swagger></p><p></p> | 說明怎麼在gin路由上加入handle                                                                                       |
| <https://github.com/swaggo/swag>                               | <p>swag tool install 工具使用 </p><p>安裝完工具後下swag version就會出現版本</p><p>下swag init就會根據註解產生對應的file<br>說明註解的用法</p> |
|                                                                |                                                                                                           |
|                                                                |                                                                                                           |
|                                                                |                                                                                                           |
|                                                                |                                                                                                           |
|                                                                |                                                                                                           |