このページは Apigee と Apigee ハイブリッドに適用されます。
Apigee Edge ドキュメントを表示する
設計フェーズで API の要件を定義します。API デザイナーは、コンシューマに公開するサービスを計画し、それらのサービスにアクセスするための API を設計します。API の要件を記録するために、次のいずれかのドキュメントを作成します。
- OpenAPI ドキュメント
- GraphQL スキーマ
以降のセクションでは、OpenAPI ドキュメントと GraphQL ドキュメント、およびそれらが API のライフサイクルで果たす役割について詳しく説明します。2 つの API 設計オプションの比較については、こちらのブログ投稿の REST と GraphQL の比較をご覧ください。
OpenAPI 仕様とは
「Open API Initiative（OAI）は、Swagger 仕様に基づいた、ベンダーに依存しない API 記述形式の作成、発展、促進に注力しています」Open API Initiative の詳細については、https://openapis.org をご覧ください。
OpenAPI ドキュメントでは、標準形式を使用して RESTful API を記述します。JSON 形式または YAML 形式で記述された OpenAPI ドキュメントは、機械判読可能でありながら、人間も簡単に読んで理解できます。OpenAPI 仕様を使用すると、ベースパス、パスと動詞、ヘッダー、クエリ パラメータ、コンテンツ タイプ、レスポンス モデルなど、API の要素を正式に記述できます。また、OpenAPI ドキュメントは API ドキュメントの生成にもよく使用されます。
次に、Apigee のシンプルな Hello World サンプルを記述した OpenAPI ドキュメントの一部を示します。詳細については、GitHub で OpenAPI 仕様をご覧ください。
openapi: 3.0.0
info:
description: OpenAPI Specification for the Apigee mock target service endpoint.
version: 1.0.0
title: Mock Target API
paths:
/:
get:
summary: View personalized greeting
operationId: View a personalized greeting
description: View a personalized greeting for the specified or guest user.
parameters:
- name: user
in: query
description: Your user name.
required: false
schema:
type: string
responses:
"200":
description: Success
/help:
get:
summary: Get help
operationId: Get help
description: View help information about available resources in HTML format.
responses:
"200":
description: Success
...
OpenAPI 仕様に関する多くの優れた情報源があります。まず出発点として役立つサイトは OpenAPI Initiative です。このサイトには、概要、ブログ、OpenAPI 仕様へのリンクが掲載されています。スキーマ要素とデータタイプの詳細な説明については、仕様を参照してください。
さまざまな JSON と YAML のサンプル OpenAPI ドキュメントがあり、OpenAPI 仕様リポジトリからダウンロードできます。
GraphQL スキーマとは
GraphQL スキーマでは、クライアントがクエリを実行するために API で使用できるデータが記述されます。
GraphQL を使用するメリットは次のとおりです。
- 単一のエンドポイントでは、特定のオペレーションのすべてのフィールドへのアクセスが提供されます。
- 強力なクエリ言語であるスキーマ定義言語を使用すると、必要なデータだけにアクセスして、データの過度な取得や不十分な取得を防ぐことができます。
- クエリは並行処理されます。
GraphQL の詳細については、graphql.org をご覧ください。
以下では、データ エントリ ポイント（クエリタイプ）、使用可能な書き込みオペレーション（ミューテーション タイプ）、データタイプを定義する GraphQL スキーマの例を提示します。
type Query {
Greeting: String
students: [Student]
}
type Mutation {
createStudent(firstName: String!, lastName: String!): Student!
}
type Subscription {
newStudent: Student!
}
type Student {
Id: ID!
firstName: String!
lastName: String!
password: String!
collegeId: String!
}
必要なデータだけを JSON ペイロードとして返すために、GraphQL スキーマに対してクエリを実行できます。
ドキュメントを変更するとどうなるか
それぞれの OpenAPI ドキュメントまたは GraphQL ドキュメントは、API ライフサイクル全体を通して信頼できる情報源として機能します。開発から公開、モニタリングまで、API ライフサイクルの各フェーズで同じドキュメントが使用されます。
ドキュメントを編集または削除すると、次のような直接的な影響があります。
- ドキュメントを編集した場合、API プロキシなどの関連アーティファクトや、そのリソースを公開する API プロダクトを手動で編集する必要があります。また、ドキュメントに実装された変更を反映するように API リファレンス ドキュメントを作り直す必要もあります。
- ドキュメントを削除した場合、API プロキシなどの関連アーティファクトを手動で削除し、API プロダクトを編集して関連リソースを削除する必要があります。また、ドキュメントとそのリソースの削除を反映するように API リファレンス ドキュメントを作り直す必要があります。
OpenAPI ドキュメントから API プロキシを作成するとどうなるか
OpenAPI ドキュメントから API プロキシを作成できます。数回クリックするだけで、パス、パラメータ、条件付きフロー、ターゲット エンドポイントがある API プロキシが自動的に作成されます。その後、OAuth セキュリティ、レート制限、キャッシュ保存などの機能を追加できます。
OpenAPI 仕様を使用したプロキシの生成で説明しているように、Create Proxy Wizard を使用して、OpenAPI ドキュメントから API プロキシを作成できます。実践的な経験を積むためには、OpenAPI 仕様から API プロキシを作成するのチュートリアルの手順を実行してください。
API を公開するときには、OpenAPI ドキュメントのスナップショットを取得して API リファレンス ドキュメントを生成します。このスナップショットでは、説明ドキュメントの特定のリビジョンが表されます。