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

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

最新のアプリケーション アーキテクチャの出現により、API (アプリケーション プログラミング インターフェイス) が最新の Web アプリケーションの基本コンポーネントになりました。 API の数が増え続けるにつれて、API ドキュメントの作成と保守は退屈な作業になってきました。したがって、API ドキュメントの作成とメンテナンスのプロセスを簡素化することが非常に必要です。 Swagger は、Web API 用の強力なドキュメント ツールを提供する人気のあるソリューションです。この記事では、SwaggerUI を使用して Golang で API オンライン ドキュメントを実装する方法を紹介します。

Swagger の概要

Swagger は、開発者が RESTful API を設計、構築、文書化、テストするのに役立つ一連のオープン ソース API 構築ツールです。これには、Swagger Editor、Swagger UI、Swagger Codegen などの複数のツールが含まれています。

その中で、Swagger Editor は、開発者が Swagger 仕様の作成と編集を支援できる Web ブラウザベースのエディタです。Swagger UI は、Swagger 仕様を API ドキュメントにレンダリングできるツールです。Swagger Codegen は、クライアント側で自動的に生成できますサーバー側の API コード。

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

Golang は非常に人気のあるプログラミング言語であり、その利点は、同時実行パフォーマンスが高く、オーバーヘッドが低いことです。 Goroutine と呼ばれる軽量スレッドを使用して同時実行を処理し、自動メモリ リサイクルとガベージ コレクションをサポートします。 Golang では、go-swagger ライブラリを使用して API オンライン ドキュメントを実装できます。

1. Swagger のインストール

まず、Swagger をインストールする必要があります。これは、次のコマンドでインストールできます。

$ brew tap go-swagger/go-swagger
$ brew install go-swagger

2. Golang の初期化project

次に、ローカル コンピューター上で Golang プロジェクトを初期化する必要があります。次のコマンドを使用して、ローカル コンピューター上に Go-Swagger-API という名前の Golang プロジェクトを作成しました:

$ mkdir Go-Swagger-API 
$ cd Go-Swagger-API 
$ go mod init Go-Swagger-API 

3. Create API Definition

API 定義を作成するには、 YAML ファイルを作成し、その中で API 設定を定義する必要があります。この例では、pets.yaml という名前のファイルを作成し、その中に次のコードを追加できます。

swagger: "2.0"
info:
  version: 1.0.0
  title: Petstore API 
produces:
- application/json
paths:
  /pets:
    get:
      summary: List all pets 
      responses:
        200:
          description: OK
        500:
          description: Internal Server Error
    post:
      summary: Add a new pet 
      parameters:
        - in: body
          name: body
          schema:
            "$ref": "#/definitions/pet"
          required: true
      responses:
        201:
          description: Created
        500:
          description: Internal Server Error

definitions:
  pet:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      tag:
        type: string

4. Generate API サーバー フレームワーク

次に、使用する必要があります。コードを生成する go-swagger ツール コード ジェネレーターは、前の手順で定義した構成を使用してコードを自動的に生成します。ターミナルに次のコマンドを入力します。

$ swagger generate server -A Go-Swagger-API -f pets.yaml

このコマンドは、YAML ファイルの定義に基づいてサーバー側のフレームワークを生成します。

5. API サーバーの起動

次に、API サーバーを起動し、正しく動作していることを確認する必要があります。ターミナルに次のコマンドを入力します:

$ cd cmd/go-swagger-api-server/
$ go run main.go

出力は次のようになります:

Serving Go-Swagger-API at http://127.0.0.1:8080 

これで、Web ブラウザで次の URL にアクセスして API が有効であることを確認できるようになります。動作しています: http://127.0.0.1:8080/pets。

6. SwaggerUI の統合

最後のステップは、SwaggerUI を API サーバーに統合することです。まず、プロジェクトのルート ディレクトリに swagger-ui という名前のディレクトリを作成し、その中に SwaggerUI をダウンロードします。これは、次のコマンドを実行することで実現できます:

$ mkdir swagger-ui && cd swagger-ui && wget https://github.com/swagger-api/swagger-ui/archive/v3.32.3.tar.gz && tar xfz v3.32.3.tar.gz --strip-components=1 && rm v3.32.3.tar.gz

次に、API の main.go ファイル内でサーバー 次のコードを追加します。

// Setup the SwaggerUI middleware
swaggerUI := http.FileServer(http.Dir("./swagger-ui/dist"))
r.PathPrefix("/docs").Handler(http.StripPrefix("/docs", swaggerUI))

このコードは、SwaggerUI の dist ディレクトリを、実際の SwaggerUI をレンダリングするための静的リソース ファイルとして公開します。

これで、ブラウザで次の URL にアクセスして、自動生成された API ドキュメントを表示できるようになります: http://localhost:8080/docs/index.html。

結論

SwaggerUI を使用して Golang で API オンライン ドキュメントを実装するのは難しくありません。これにより、API ドキュメントの作成とメンテナンスが非常に便利になります。 Swaggerを利用することでAPIのドキュメントを自動生成でき、バックエンドエンジニアやフロントエンドエンジニアもAPIインターフェースを素早く理解できるようになります。これにより、API の開発、テスト、ドキュメントのプロセスが大幅に簡素化され、開発者はビジネス ロジックの実装により集中できるようになります。

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