Golang API ドキュメントを生成するために swag をインストールする方法

Swag は、Swagger ドキュメントを自動的に生成する Go アプリケーションを迅速に構築するためのツールです。開発者は、コードにコメントを追加するだけで、API ドキュメントを自動的に生成できます。 Swag は、RESTful API 標準に従って API ドキュメントの生成をサポートし、Markdown 形式と HTML 形式の生成もサポートします。

この記事では、golang に Swag をインストールして使う方法を紹介します。

ステップ 1 - Swag のインストール

Swag は go get コマンドを使用して GitHub からインストールできます。次のコマンドを使用して Swag をインストールします:

$ go get github.com/swaggo/swag/cmd/swag

インストールが完了したら、 $GOPATH/ にインストールできます。bin パスで「swag」バイナリ ファイルを見つけます。これで、Swag を使用して API ドキュメントを生成し続けることができます。

ステップ 2 - API ドキュメントの生成

Swag で API ドキュメントを正しく生成するには、いくつかの特別なコード コメントが必要です。コメントのサンプルをいくつか示します。

// @Summary 创建用户
// @Description 创建一个新用户
// @Tags 用户管理
// @Accept json
// @Produce json
// @Param user body User true "用户信息"
// @Success 200 {string} string "成功"
// @Failure 400 {string} string "请求错误"
// @Failure 500 {string} string "服务器内部错误"
// @Router /users [post]
func CreateUser(c *gin.Context) {
    // ...
}

上記のコメントは、ユーザーの作成方法に関する API について説明しています。 Swag はコード内でこれらの特別なコメントを検索し、ドキュメントを構築します。

次のコマンドを実行してドキュメントを生成します:

$ swag init

これにより、アプリケーションがスキャンされ、Swagger JSON ファイルと Swagger UI が生成されます。

ステップ 3 - Swagger の UI を追加する

Swagger UI は、API を表示およびテストするための対話型インターフェイスを提供します。 Swagger UI を Web アプリケーションに追加できます。

// main.go
package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
    "github.com/swaggo/files" // swagger embed files
    "github.com/swaggo/gin-swagger" // gin-swagger middleware
    _ "github.com/user/repo/docs" // docs is generated by Swag CLI, you have to import it.
)

func main() {
    r := gin.New()

    // use ginSwagger middleware to serve the API docs
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    //...
}

Swag を使用してドキュメントを生成したと仮定します。これで、ブラウザで次のリンクを開いて API ドキュメントを表示できるようになります。

http://localhost:8080/swagger/index.html

これは、API の表示とテストに使用できる Swagger の Web UI です。

まとめ

この記事では、Golang に Swag をインストールして使用する方法を紹介しました。 Swagger の注釈とコマンドを使用すると、API ドキュメントを簡単に生成できます。 Swag を使用すると、プロセス全体が迅速かつ簡単になり、Swag を使用したドキュメントは Swagger UI

とうまく統合されます。

以上がGolang API ドキュメントを生成するために swag をインストールする方法の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。