第4章 3scale OpenAPI 仕様として使用する OpenAPI ドキュメントの作成方法

コードを読むだけであれば、すべての例は OAS Petstore のソースコード例 に記載されています。

3scale ActiveDocs は、Swagger と呼ばれる RESTful Web サービスの仕様をベースにしています (Wordnik より)。この例は、拡張された OpenAPI Specification の Petstore の例 をベースにしており、すべての仕様データを OpenAPI Specification 2.0 の仕様ドキュメント から引用しています。

前提条件

  • デベロッパーポータルで ActiveDocs を動作させるには、REST API に対する OpenAPI Specification (OAS) 準拠の仕様が必要です。

OAS は単なる仕様ではありません。あらゆる機能のフレームワークも提供します。

  • 複数の言語 (NodeJS、Scala、その他) によるリソース仕様のサーバー
  • 仕様ファイルを使用して開発者を引き付ける UI を生成する、さまざまな HTML/CSS/Javascripts アセット
  • Swagger 準拠サーバーからクライアントライブラリーを自動的に生成することのできる、OAS codegen プロジェクト。数多くの現代的な言語によるクライアント側のライブラリー作成をサポートします。

4.1. 3scale ActiveDocs および OAS の設定

ActiveDocs とは OAS のインスタンスのことです。ActiveDocs を使用する場合に、独自の OAS サーバーを実行したり、インタラクティブドキュメントのユーザーインターフェースコンポーネントを扱ったりする必要がありません。インタラクティブドキュメントは、3scale のデベロッパーポータルから提供され、レンダリングされます。

3scale 2.8 では、OAS 3.0 が導入されましたが、ActiveDocs でのサポートは限定でした。つまり、自動補完などの ActiveDocs を使用する機能の一部が完全に統合されていないため、新しいアカウントの作成時にデフォルトの 3scale は OAS 2.0 に設定されます。OAS 3.0 および ActiveDocs の詳細は、「3scale での OpenAPI Specification 3.0 の使用」を参照してください。

前提条件

  • デベロッパーポータルで使用するテンプレートが、管理ポータルで指定した OAS バージョンと同じものであることを確認します。

手順

  1. OAS に準拠する API 仕様を構築します。
  2. 管理ポータルに仕様を追加します。

結果

API 用のインタラクティブなドキュメントが利用できるようになりました。API 利用者は、デベロッパーポータルを通じて API にリクエストを送信することができます。

すでに OAS 準拠の API 仕様がある場合は、それをデベロッパーポータルに追加できます。「ActiveDocs の設定に関するチュートリアル」を参照してください。

3scale では OAS 仕様をさまざまな方法で拡張し、デベロッパーポータルでのインタラクティブな API ドキュメント作成で必要となった特定の機能に対応しました。

  • API キーの自動入力
  • CORS 非対応 API への呼び出しを許可する OAS プロキシー