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

ホットAIツール

Undresser.AI Undress
リアルなヌード写真を作成する AI 搭載アプリ

AI Clothes Remover
写真から衣服を削除するオンライン AI ツール。

Undress AI Tool
脱衣画像を無料で

Clothoff.io
AI衣類リムーバー

AI Hentai Generator
AIヘンタイを無料で生成します。

人気の記事

ホットツール

メモ帳++7.3.1
使いやすく無料のコードエディター

SublimeText3 中国語版
中国語版、とても使いやすい

ゼンドスタジオ 13.0.1
強力な PHP 統合開発環境

ドリームウィーバー CS6
ビジュアル Web 開発ツール

SublimeText3 Mac版
神レベルのコード編集ソフト(SublimeText3)

ホットトピック











Go ではファイルを安全に読み書きすることが重要です。ガイドラインには以下が含まれます。 ファイル権限の確認 遅延を使用してファイルを閉じる ファイル パスの検証 コンテキスト タイムアウトの使用 これらのガイドラインに従うことで、データのセキュリティとアプリケーションの堅牢性が確保されます。

Go データベース接続の接続プーリングを構成するにはどうすればよいですか?データベース接続を作成するには、database/sql パッケージの DB タイプを使用します。同時接続の最大数を制御するには、MaxOpenConns を設定します。アイドル状態の接続の最大数を設定するには、ConnMaxLifetime を設定します。

Golang と C++ は、それぞれガベージ コレクションと手動メモリ管理のプログラミング言語であり、構文と型システムが異なります。 Golang は Goroutine を通じて同時プログラミングを実装し、C++ はスレッドを通じて同時プログラミングを実装します。 Golang のメモリ管理はシンプルで、C++ の方がパフォーマンスが優れています。実際の場合、Golang コードはより簡潔であり、C++ には明らかにパフォーマンス上の利点があります。

Go フレームワーク アーキテクチャの学習曲線は、Go 言語とバックエンド開発への慣れ、選択したフレームワークの複雑さ、つまり Go 言語の基本の十分な理解によって決まります。バックエンドの開発経験があると役立ちます。フレームワークの複雑さが異なると、学習曲線も異なります。

Golang でリストのランダムな要素を生成する方法: rand.Intn(len(list)) を使用して、リストの長さの範囲内でランダムな整数を生成し、その整数をインデックスとして使用して、リストから対応する要素を取得します。

Go フレームワークは、その高いパフォーマンスと同時実行性の利点で際立っていますが、比較的新しい、開発者エコシステムが小さい、一部の機能が欠けているなどの欠点もあります。さらに、急速な変化と学習曲線はフレームワークごとに異なる場合があります。 Gin フレームワークは、効率的なルーティング、組み込みの JSON サポート、強力なエラー処理機能により、RESTful API を構築するための一般的な選択肢です。

ベスト プラクティス: 明確に定義されたエラー タイプ (エラー パッケージ) を使用してカスタム エラーを作成する 詳細を提供する エラーを適切にログに記録する エラーを正しく伝播し、非表示または抑制しないようにする コンテキストを追加するために必要に応じてエラーをラップする

Go フレームワークのドキュメントを使用するにはどうすればよいですか?ドキュメントの種類を決定します: 公式 Web サイト、GitHub リポジトリ、サードパーティのリソース。ドキュメントの構造 (入門書、詳細なチュートリアル、リファレンス マニュアル) を理解します。必要に応じて情報を見つけます。組織構造または検索機能を使用します。用語と概念を理解する: 新しい用語と概念を注意深く読んで理解します。実際のケース: Beego を使用して単純な Web サーバーを作成します。その他の Go フレームワークのドキュメント: Jin、Echo、Buffalo、Fiber。
