Golang で SwaggerUI を使用して API オンラインドキュメントを自動化する-Golang-php.cn

Golang で SwaggerUI を使用して API オンラインドキュメントを自動化する

王林

リリース： 2023-06-03 20:10:31

オリジナル

1316 人が閲覧しました

Golang での API オンラインドキュメントの自動化に SwaggerUI を使用する

API (アプリケーションプログラミングインターフェイス) の使用は、最新のアプリケーション開発において必要な要素となっています。 API により、フロントエンドとバックエンドの分離、マイクロサービス、クラウドアプリケーションが容易になります。ただし、優れた API は機能を実装するだけでなく、ユーザーフレンドリーで使いやすいものです。このため、文書化された API の重要性がますます高まっています。オンラインドキュメントの利点は、API を操作する前に API について学ぶことができることです。

この記事では、SwaggerUI を使用して API ドキュメントを記録する方法と、このプロセスを Golang で自動化する方法を紹介します。これにより、他のチームやパートナーが理解できるように、読みやすいドキュメントの維持と提供が容易になります。 API。

SwaggerUI は、API のドキュメントの作成、インタラクティブな API ドキュメントの生成、視覚的な方法で API を説明するための一般的なツールであり、人間が読めるドキュメントと機械が読める JSON または YAML の両方を生成できます。 SwaggerUI は、Golang を含む多くのプログラミング言語と統合します。

まず、SwaggerUI の Golang 実装である Swag を使用する必要があります。 Swag は、Go 言語のアノテーションと Swagger アノテーションを組み合わせて Swagger 2.0 ドキュメントを自動的に生成する自動 API ドキュメントツールです。

ステップ 1: Swag をインストールする

ターミナル/cmd で次のコマンドを使用して、Swag をダウンロードしてインストールします:

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

ログイン後にコピー

ステップ 2: コードに Swagger 注釈を追加します

API を説明するコードに Swagger コメントを追加します。

HTTP ハンドラー関数の上のコメントに Swagger アノテーションを追加します。例:

// GetByID godoc
// @Summary Get user details by ID
// @Description Get user details by ID
// @Tags user
// @Accept json
// @Produce json
// @Param id path int true "User ID"
// @Success 200 {object} model.User
// @Failure 400 {object} ErrorResponse
// @Router /users/{id} [get]
func GetByID(c *gin.Context) {
    //…code here…
}

ログイン後にコピー

ステップ 3: Swagger JSON ファイルを生成する

次のコマンドをルートディレクトリで使用します。コードベース Swagger JSON ファイルを生成する場所:

swag init

ログイン後にコピー

このコマンドは、コード内で Swagger アノテーションを使用し、Swagger JSON ファイルを生成します。プロジェクトの Makefile に追加することもできます。

ステップ 4: SwaggerUI の統合

Swag は、ブラウザーで API ドキュメントを表示するためのフロントエンドとして SwaggerUI を使用します。SwaggerUI 内のファイルをアプリケーションに静的にリバースプロキシする必要があります。

Golang アプリケーションがポート 8080 で実行されていると仮定します。使用する SwaggerUI のバージョンは v3.31.1 です。これは、SwaggerUI の公式 GitHub ページから次の方法でダウンロードできます。

curl -L https://github.com/swagger-api/swagger-ui/archive/v3.31.1.tar.gz -o swagger-ui.tar.gz
tar -xf swagger-ui.tar.gz

ログイン後にコピー

これにより、SwaggerUI のすべてのファイルが含まれる swagger-ui フォルダーがローカルディレクトリに生成されます。 nginx をリバースプロキシサーバーとして使用します (Apache、Caddy などを使用できます)。ターミナル/cmd で次のコマンドを使用して nginx を起動します:

nginx -c /path/to/nginx.conf

ログイン後にコピー

nginx.conf ファイルに、以下を追加する必要があります。以下:

http {
  server {
    listen 8081; # 访问静态文件的端口
    server_name _;
    root /path/to/swagger-ui/dist;

    location / {
      try_files $uri $uri/ @go;
    }

    location @go {
      proxy_redirect off;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_pass http://127.0.0.1:8080; # 代理请求的端口
    }

    location /swagger-ui/ {
      try_files $uri $uri/ =404;
    }
  }
}

ログイン後にコピー

上記の nginx 構成では、静的 SwaggerUI フォルダー /swagger-ui/dist ディレクトリを静的ファイルとして nginx サーバーのルートディレクトリに追加し、localhost:8080 にプロキシします。独自のアプリケーション ) は、ポート 8081 によってリッスンされるポートに転送されます。 http://localhost:8081/swagger-ui/ にアクセスして SwaggerUI を表示および使用します。

ステップ 5: API ドキュメントを表示する

ブラウザで http://localhost:8081/swagger-ui/ にアクセスすると、SwaggerUI アプリケーションにより、ルートに表示される SwaggerUI 静的ファイルが表示されます。ディレクトリフォルダ。このページには、十分に文書化されたすべての API のリストがあります。表示したい API ドキュメントをクリックすると右側に表示されます。この Web サイトは、API 上で直接 API ドキュメントをテストおよび表示するための API ユーザーフレンドリーなインターフェイスを提供します。このプロセス中、GUI には、この API のパラメーター、本体情報、API バージョン、API 形式などの、Swagger アノテーションによって自動的に抽出された詳細情報が表示されます。これにより、ドキュメントを作成する時間と労力が大幅に節約されます。

結論

API ドキュメントは API の設計および開発プロセスにおいて重要なツールであるため、アプリケーションを構築する際にはドキュメント化された API を考慮する必要があります。自動化ツール Swag を使用すると、Golang で API ドキュメントを簡単に自動化できます。文書化された API を表示およびテストするための視覚化ツールとして SwaggerUI を使用することも非常に便利です。これにより、他のチームやコラボレーションパートナーが API を理解しやすくなります。

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