OpenAPI/Swagger を使用して Go 言語で API ドキュメントを作成する

近年、インターネット技術の継続的な発展に伴い、Web API インターフェースの重要性がますます高まっており、API ドキュメントの作成は開発作業の重要な部分となっています。 Go 言語では、OpenAPI/Swagger を使用して API ドキュメントを作成できます。

OpenAPI/Swagger は、RESTful アーキテクチャ スタイルに準拠した API インターフェイスの構築と記述に役立つ API 仕様およびツール チェーンです。これには、標準化された API 記述言語のセットと、API ドキュメント、クライアント コード、サーバー フレームワークの自動生成に役立つ一連のツールが含まれています。

Go 言語では、Swagger の Go 公式実装「swag」を使用して API ドキュメントを迅速に生成できます。以下では、swag を使用して API ドキュメントを作成する方法を学びます。

まず、プロジェクトにスワッグを追加する必要があります。次のコマンドを使用してプロジェクトに追加できます:

go get -u github.com/swaggo/swag/cmd/swag

スワッグをインストールした後、スワッグ関連情報をmain.go ファイル パッケージ:

import (
    "github.com/swaggo/files"
    "github.com/swaggo/gin-swagger"
    "github.com/gin-gonic/gin"
)

// 注册swag
func setUpSwagger(engine *gin.Engine) {
    engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}

func main() {
    // 初始化 gin 引擎
    engine := gin.Default()
    setUpSwagger(engine)
    router.LoadRouters(engine)
    _ = engine.Run()
}

次に、swagger アノテーションを使用して、インターフェイス アノテーションでインターフェイスを記述することができます。例:

// User register router
// @Summary User register router
// @Description User register router
// @Tags Users
// @Accept  json
// @Produce  json
// @Param user_in body models.NewUser true "user info"
// @Success 200 {string} json "{"code":200,"data":null,"msg":"Register successful"}"
// @Failure 400 {string} json "{"code":400,"msg":"Bad Request"}"
// @Router /users/register [post]
func Register(c *gin.Context) {
    name := c.PostForm("name")
    password := c.PostForm("password")
    ...
}

コメントでは、いくつかの Swagger 注釈を使用します:

• @summary: インターフェイスの概要情報
• @Description: インターフェイスの詳細な説明
• @Tags: インターフェースが属するタグ
• @Accept: インターフェース要求 Content-Type
• @Produce: インターフェース応答 Content-Type
• @Param:インターフェイス パラメーターの説明 (パラメーターの位置、パラメーター名、必須パラメーターかどうか、パラメーターの説明、およびパラメーターの例を含む)
• @Success: インターフェイスの成功した応答の説明。応答コード、応答情報、応答データ構造を含めることができます
• @Failure: インターフェイス障害応答の説明。応答コードと応答情報も含まれる場合があります。
##最後に、プロジェクト ルート ディレクトリで swag init コマンドを使用して API ドキュメントを生成する必要があります。ドキュメントは docs ディレクトリに生成されます。

swag init

これで、http://localhost:8080/swagger/index.html にアクセスして API ドキュメントを表示できるようになります。

一般に、OpenAPI/Swagger を使用して API ドキュメントを作成すると、インターフェイスをより明確に記述し、読みやすく理解しやすくなります。 Go 言語の Swag ライブラリを使用すると、API ドキュメントを迅速に生成できるため、より効率的に開発できます。

以上がOpenAPI/Swagger を使用して Go 言語で API ドキュメントを作成するの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。