この記事はHowtelevision Advent Calendar 2023 21日目の記事です。

20日目はkikaiさん (id: taiki-kikai) の「Nuxt2 → Nuxt3 アップデート最前線！最大の難関「脱 Vuex」をどのように乗り越えたか」でした。

私たちの取り組んでいる技術負債解消プロジェクトでは、BE側でgolangのginフレームワークを使っています。開発の際にはエンドポイントのドキュメントを作成するのですが、なかなか時間がかかってしまうと感じていました。そこで、以前の職場で使っていたSwaggoを活用できないかと考えました。Swaggoを利用すると、手軽かつ効果的にAPIのドキュメントを自動生成することができます。今回のブログではSwaggoの紹介と使い方について解説します。

Swaggoとは？

github.com

Swaggoは、Go言語で開発されたAPIのドキュメンテーションツールです。Swagger（OpenAPI Specification）をベースにしており、APIの設計からドキュメント生成までをサポートしています。これにより、開発者は手動でドキュメントを書く手間を省き、かつ統一された仕様書を生成できます。

導入手順

Swaggoのインストール：プロジェクトのディレクトリで go get -u github.com/swaggo/swag/cmd/swag を実行し、Swaggoを導入します。
コード内にAPIのドキュメンテーションをコメントで記述します。
最後に、ターミナルでswag initコマンドを実行し、ドキュメントを生成します。

実際に使ってみよう

プロジェクトストラクチャー

.
├── app
│   ├── config
│   ├── console
│   ├── constants
│   ├── docs              # ここでswaggerファイルを保存
│   ├── logic
│   ├── model
│   ├── reopsitory
│   ├── router
│   ├── services
│   └── utils
├── go.mod
├── go.sum
├── main.go
└── README.md

swaggoインストール

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

# command not found: swagのエラーが出る時以下で試してみてください
export PATH=$(go env GOPATH)/bin:$PATH

swaggerファイルを可視化するためgin-swaggerインストール

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

構造体の定義

// model/User.go

package model

type User struct {
    ID          int    `json:"id" example:"1"`
    Name        string `json:"name" example:"John"`
    Age         int    `json:"age" example:"20"`
    Address     string `json:"address" example:"Tokyo"`
    PhoneNumber string `json:"phone_number" example:"080-1234-5678"`
}

リクエスト定義

type GetUserRequest struct {
    Name        string `json:"name" example:"John" binding:"required"`
    PhoneNumber string `json:"phone_number" example:"080-1234-5678" binding:"required"`
}

Controllerに簡単で試す

// @BasePath /api/v1

// GetUser godoc
//
// @Summary ユーザー情報取得
// @Description ユーザー情報取得
// @Accept  json
// @Produce  json
// @Security ApiKeyAuth
// @Param id path int true "ID"
// @Param request body GetUserRequest true "リクエスト"
// @Success 200 {object} model.User
// @Failure 400 {string} string "400 error"
// @Failure 404 {string} string "404 error"
// @Failure 500 {string} string "500 error"
// @Router /users/{id} [get]
func GetUser(ctx *gin.Context) {
    var request GetUserRequest
    if err := ctx.BindJSON(&request); err != nil {
        ctx.JSON(http.StatusBadRequest, err)
    }

    ctx.JSON(http.StatusOK, model.User{
        ID:          1,
        Name:        request.Name,
        Age:         20,
        Address:     "Tokyo",
        PhoneNumber: request.PhoneNumber,
    })
}