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

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