go-ginチュートリアル — Part7

GinのBlog API’s 作成 — Swagger追加

前回Testing＆CI周りを追加しました。今回Swaggerを追加します。APIsの一番重要な部分は Docs だと思います。手動で APIs Docs を作成するのは無理です。Swaggerを使い、Docsを自動生成します。

関連パッケージを入れましょう。

Add swag

~ ❯❯❯ go get -u github.com/swaggo/swag/cmd/swag
~ ❯❯❯ swag --version
swag version v1.4.0

Add gin-swagger

~ ❯❯❯ go get -u github.com/swaggo/gin-swagger
~ ❯❯❯ go get -u github.com/swaggo/gin-swagger/swaggerFiles

Docsの初期化

APIsにコメントを入れます。Swaggerがコメントから Docsを自動作成します。

go-swaggerの例はこちらです。

// @Summary Add a new pet to the store
// @Description get string by ID
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string	"ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-string-by-int/{some_id} [get]

Swaggerの例を参照し、我々のAPIsのコメントを入れます。下記のようになります。

// @Summary 新規記事タク
// @Produce  json
// @Param name query string true "Name"
// @Param state query int false "State"
// @Param created_by query int false "CreatedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [post]
func AddTag(c *gin.Context) {
// @Summary 修正記事タク
// @Produce  json
// @Param id param int true "ID"
// @Param name query string true "ID"
// @Param state query int false "State"
// @Param modified_by query string true "ModifiedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags/{id} [put]
func EditTag(c *gin.Context) {

詳細の部分はsample codeをご参照ください。

Docs 作成

gin-blogフォルダに初期化コマンドを実行します。

~/g/s/g/g/hello-gin ❯❯❯ swag init
2018/11/18 00:07:49 Generate swagger docs....
2018/11/18 00:07:49 Generate general API Info
2018/11/18 00:07:49 create docs.go at  docs/docs.go

プロジェクトフォルダに docsフォルダを生成しました。下記となります。

docs
├── docs.go
└── swagger
    ├── swagger.json
    └── swagger.yaml

routers.go に作った docs の部分を追加します。

import (
...

	"github.com/swaggo/gin-swagger"
	"github.com/swaggo/gin-swagger/swaggerFiles"
	
	_ "github.com/gavinzhou/hello-gin/docs"
)

func InitRouter() *gin.Engine {
...

	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

サーバを再起動したら、アクセスしてみてください。下記の様な画面が表示します。

参考サイト

• sample code
• https://swagger.io/
• gin-swagger

※問題があった場合は、githubの issue をお願いします。