Swagger を使用して Beego で API ドキュメントを自動生成する

Beego で Swagger を使用して API ドキュメントを自動的に生成する

インターネット テクノロジーがますます成熟するにつれて、ますます多くの企業がビジネス モデルをデジタル変革し始めており、API はデジタル変革の重要な部分です。ますます重要になっています。 APIを開発する際には、APIのセキュリティや信頼性を確保するだけでなく、他のフロントエンドやバックエンドの開発エンジニアが自分が開発したAPIをいかに早く理解して利用できるかということも非常に重要な部分となります。この記事では、Beego フレームワークを使用して API を開発するときに、Swagger ツールを使用して API ドキュメントを自動的に生成し、他の開発エンジニアの呼び出しと使用を容易にする方法を紹介します。

Swagger とは何ですか?

Swagger は、API の開発と使用を簡素化および標準化することを目的としたオープン ソースの API 仕様およびツールセットです。開発者、消費者、ドキュメント間の対話型インターフェイスを自動的に生成でき、多くの視覚的なヘルプ ドキュメント機能を提供します。

Swagger を使用する理由

一部の API には、その使用方法と呼び出し方法を理解するためにドキュメントと説明が必要です。Swagger を使用すると、これらのドキュメントを簡素化し、自動的に生成できます。 Swagger ツールを使用すると、生成時に API ドキュメントをより美しく、標準化し、読みやすくすることができます。 Swagger の必須形式は、開発者が標準化された仕様に準拠する API を設計および実装するのにも役立ち、時間とエネルギーを節約できます。

Beego での Swagger の使用

1. 依存関係の追加

Beego プロジェクトで Swagger を使用するには、Swagger ライブラリの依存関係をまずはプロジェクト。次のコマンドを使用してインストールできます。

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/gin-swagger/swaggerFiles

2. Swagger コメントの編集

Beego フレームワークでは、Router コード内のコメントを使用して API パラメーターとリクエストを説明します。型、戻り値、その他の情報 Swagger を使用する場合、API ドキュメントを自動的に生成するには、これらのコメントに Swagger 仕様タグを追加する必要があります。

次は簡単な例です:

// @Summary  获取一个用户信息
// @Description 通过ID获取一个用户信息
// @Accept  json
// @Produce  json
// @Param   id     path    int     true        "用户ID"
// @Success 200 {object} models.User
// @Router /users/{id} [get]
func GetUser(c *gin.Context) {
    // ...
}

コメントに、いくつかの特別な仕様タグを追加しました:

• @概要: API メソッドの概要
• @Description: API メソッドの詳細説明
• @Accept: 受け入れられた Content-Type type
• @Produce: Response Content-Type type
• @ Param:パラメータ名、場所、データ型、必須かどうか、および説明を含むリクエストパラメータ。
• @Success: HTTP ステータス コードと成功応答の戻り値の種類。配列、構造体、その他の情報も含まれる場合があります。
• @Router: リクエスト パスとリクエスト メソッド。

必要に応じて、さらにタグを追加して API の説明を補足できます。

3. ドキュメントの自動生成

Swagger 仕様のコメントをコードに追加した後、プロジェクトのルート ディレクトリで次のコマンドを実行して API ドキュメントを生成します。

swag init

このコマンドは、プロジェクト ディレクトリに docs フォルダーを生成します。このフォルダーには、生成された API ドキュメントと静的リソース ファイルが含まれます。

SwaggerUI を使用して API ドキュメントを表示する

生成されたドキュメントをフロントエンド開発者に直接送信すると、開発者に不必要なプレッシャーがかかることになります。 API ドキュメントをよりわかりやすく、使いやすくするために、API ドキュメントを表示するための SwaggerUI を導入できます。

まず、SwaggerUI の静的リソース ファイルをプロジェクトにコピーする必要があります。次に、パス /swagger/*any でルーターを作成し、SwaggerUI をプロジェクトに関連付けます:

r.StaticFS("/swagger", http.Dir("docs"))

次、ブラウザで http://localhost:8080/swagger/index.html にアクセスし、自動生成された API ドキュメントを確認します。

概要

Beego で Swagger を使用すると、アノテーションを通じて API の定義を標準化し、開発者が使いやすい美しい API ドキュメントを生成できます。同時に、SwaggerUI の導入により、API の表示と対話がさらに簡素化され、開発が加速されます。

参考資料:

https://www.cnblogs.com/wuyun-blog/p/10540875.html

https://github.com/swaggo/ gin-swagger

https://github.com/swaggo/swag

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