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 サイトの他の関連記事を参照してください。