プロジェクトに Swagger UI を追加する

OpenAPI 仕様を使用して、双方向型の文書化ツールである Swagger UI を設定できます。

Swagger UI のインストール

以下のセクションでは、さまざまな言語用の Swagger UI をインストールする方法を説明します。

Node.js 用のインストール

このセクションでは、OpenAPI 設定ファイル openapi.yaml に基づいて動作する nodejs アプリケーションが存在することを前提としています。存在しない場合は、サンプルアプリを使用してください。

  1. Swagger UI および Swagger Tools パッケージをインストールします。

    npm install swagger-ui
    npm install swagger-tools
    npm install yamljs
    
  2. メインサーバーのファイルの最初に次の要件を追加します。

    var swaggerTools = require('swagger-tools');
    var YAML = require('yamljs');
    var swaggerDoc = YAML.load('openapi.yaml');
    
  3. Swagger UI を初期化する次のコードをアプリに追加します。

    swaggerTools.initializeMiddleware(swaggerDoc, function (middleware) {
      // Serve the Swagger documents and Swagger UI
      app.use(middleware.swaggerUi());
    });
    
  4. アプリを起動した後、http://<yourapp>/docs を参照し、Swagger UI を使用して API を操作します。

他の言語とフレームワーク用のインストール

Node.js 以外の言語用に Swagger UI をインストールするには:

  1. 一時ディレクトリに git レポジトリのクローンを作成します。

    mkdir tmp
    cd tmp
    git clone https://github.com/swagger-api/swagger-ui.git
    
  2. git レポジトリのローカルコピーからプロジェクト内のフォルダに、dist フォルダをコピーします。この例では、プロジェクトのフォルダは docs です。

    cd swagger-ui
    cp -R dist /yourproject/docs
    
  3. openapi.yaml ファイル内の host プロパティの名前が API の完全修飾ドメイン名(FQDN)であることを確認します。

  4. swagger UI を追加するために、アプリの app.yaml を編集してハンドラのロケーションを指定します。

    handlers:
      - url: /docs
        static_files: docs/index.html
        upload: docs/index.html
      - url: /docs/(.*)
        static_files: docs/\1
        upload: docs/.
    
  5. /yourproject/docs/index.html を編集し、url 属性を変更します。

    url = "../api-docs";
    

    こうすることで、Swagger UI にこの URL から OpenAPI 仕様が取り込まれるようになります。このパスに対して、openapi.yaml を読み取って json として提供するハンドラを追加します。

  6. アプリをデプロイした後、http://<yourapp>/docs を参照し、Swagger UI を使用して API を操作します。

フィードバックを送信...

OpenAPI を使用した Cloud Endpoints