Flex Gateway新着情報
Governance新着情報
Monitoring API ManagerAPI Designer のテキストエディターの右側のペインには、API 仕様に書き込まれるドキュメントが表示されます。ドキュメントは、RAML または OAS 2.0 で作成された REST API 仕様と同様に表示されます。OAS 3.0 に書き込まれる API 仕様のドキュメントには、複数のサーバー定義や、リンクおよびコールバックが含まれることがあります。
OAS 3.0 では、servers
項目を使用してサーバーを定義できます。サーバーは仕様の最上部でグローバルに定義したり、エンドポイントやメソッドでローカルに定義したりできます。ローカル定義は、仕様の階層の次に高いレベルで設定された定義を上書きします。メソッドでローカルに設定された定義は、エンドポイントで設定された定義やグローバルに設定された定義を上書きます。エンドポイントでローカルに設定された定義は、グローバルに設定された定義を上書きます。
次の API 仕様の例は、サーバー定義を設定するさまざまな方法 (1 ~ 10 のコールアウト) を示しています。API 仕様の例の後に、API の各コールアウトの部分のドキュメントがスクリーンショットと共に記載されています。
openapi: '3.0.2' info: title: Multi-server Cemo API version: '1.0' servers: (1) - url: https://{customerId}.saas-app.com:{port}/v2 variables: customerId: default: demo description: Customer ID assigned by the service provider port: enum: - '443' - '8443' default: '443' - url: https://{region}.api.company.com variables: region: default: westus enum: - westus - eastus2 - westcentralus - westeurope - southeastasia - url: https://api.company.org/data/2.5/ description: Production server - url: http://beta.api.company.org/data/2.5/ description: Beta server paths: /default:(2) description: A default path to the API get:(3) summary: "The get method for /default" responses: 200: description: Successful response /duplicated:(4) description: Has some of the default servers servers: - url: https://api.company.org/data/2.5/ description: Production server - url: http://beta.api.company.org/data/2.5/ description: Beta server get:(5) summary: "The get method for /duplicated" responses: 200: description: Successful response /files:(6) description: File upload and download operations servers: - url: https://files.example.com description: Override base path for all operations with the /files path get:(7) summary: "The get method for /files" responses: 200: description: Successful response /ping:(8) servers: - url: https://endpoint.example.com description: Override base path servers get:(9) servers: - url: https://echo.example.com description: Override base path for the GET /ping operation - url: https://echo2.example.com description: Also overrides base path for the GET /ping operation summary: "The get method for /ping" responses: 200: description: Successful response post:(10) summary: "The post method for /ping" responses: 201: description: Successful create
この API のドキュメントの [Summary (概要)] ページには、次の servers
項目で定義されている 4 つのサーバーがリストされています。
/default
エンドポイントは、API の最上部のベース servers
定義を上書きしません。エンドポイントの [Overview (概要)] ページでは、サーバーを選択して、そのサーバーのこのエンドポイントの URI を確認できます。
/default
エンドポイントの GET メソッドは、ベース servers
定義の 4 つのサーバーも継承します。このメソッドのページでは、サーバーを選択して、そのサーバーのこのメソッドの URI を確認できます。
/duplicated
エンドポイントは、ベース servers
定義を上書きします。そのローカル servers
定義には、元の 4 つのサーバーのうち最後の 2 つのサーバーのみが含まれます。エンドポイントの [Overview (概要)] ページでは、サーバーを選択して、そのサーバーのこのエンドポイントの URI を確認できます。
/duplicated
エンドポイントの GET メソッドは、ローカル servers
定義の 2 つのサーバーを継承します。このメソッドのページでは、サーバーを選択して、そのサーバーのこのメソッドの URI を確認できます。
/files
エンドポイントは、ベース servers
定義を上書きします。そのローカル servers
定義には、1 つのサーバーのみが含まれます。このエンドポイントの [Overview (概要)] ページには、前の 2 つのエンドポイントのように選択するサーバーがありません。
/files
エンドポイントの GET メソッドは、ローカル servers
定義の 1 つのサーバーを継承します。このメソッドのページには、選択するサーバーのリストはありません。
/ping
エンドポイントは、ベース servers
定義を上書きします。そのローカル servers
定義には、1 つのサーバーのみが含まれます。このエンドポイントの [Overview (概要)] ページには、選択するサーバーがありません。
/ping
エンドポイントの GET
メソッドは、ベース servers
定義と /ping
エンドポイントのローカル servers
定義の両方を上書きします。GET
メソッドのローカル servers
定義には、2 つのサーバーが含まれます。このメソッドのページでは、サーバーを選択して、そのサーバーのこのメソッドの URI を確認できます。
/ping
エンドポイントの POST メソッドは、/ping
エンドポイントのローカル servers
定義の 1 つのサーバーを継承します。このエンドポイントの [Overview (概要)] ページには、選択するサーバーのリストがありません。
OAS 3.0 では、リンクとコールバックを定義できます。これらの機能については、\https://swagger.io/ の openAPI 3.0 の仕様を参照してください。
次の API 仕様の例は、リンクとコールバックの設定方法を示しています。コールアウトは、後に続くスクリーンショットのドキュメントとして表示される API 仕様の部分を示しています。
openapi: 3.0.0 info: version: 1.0.0 title: Callback Demo API servers: - url: https://{customerId}.saas-app.com:{port}/v2 variables: customerId: default: demo description: Customer ID assigned by the service provider port: enum: - '443' - '8443' default: '443' components: requestBodies: callbackMessage1: description: Callback message `1` required: true content: application/json: schema: $ref: '#/components/schemas/Clb1' callbackMessage2: description: Callback message `2` required: true content: application/json: schema: $ref: '#/components/schemas/Clb2' callbackMessage3: description: Callback message `3` required: true content: application/json: schema: $ref: '#/components/schemas/Clb3' schemas: Clb1: title: Event 1 type: object properties: text: type: string description: Message text Clb2: title: Event 2 type: object properties: productId: type: string description: Order product id Clb3: title: Event 3 type: object properties: eventId: type: string description: Event internal ID triggerAuthor: type: string description: A person triggered the event paymentRequest: title: Payment type: object properties: token: type: string description: Payment token generated for this request amount: type: number description: The payment amount. paths: /subscribe: post: requestBody: content: application/json: schema: type: object properties: inProgressUrl: type: string failedUrl: type: string successUrl: type: string responses: '200': description: OK links:(1) unsubscribeOp: operationId: unsubscribeOperation parameters: Id: $response.body#/subscriberId otherOp: parameters: one: $response.body#/one two: $response.body#/two 402: description: Not OK. Payment is required content: application/json: schema: $ref: '#/components/schemas/paymentRequest' links:(2) paymentUrl: parameters: paymentUrl: $response.body#/info.paymentUri paymentToken: $response.body#/info.token callbacks: inProgress: '{$request.body#/inProgressUrl}':(3) post: requestBody: $ref: '#/components/requestBodies/callbackMessage1' responses: '200': description: OK '{$request.body#/failedUrl}':(4) post: requestBody: $ref: '#/components/requestBodies/callbackMessage2' responses: '200': description: OK '{$request.body#/successUrl}':(5) post: requestBody: $ref: '#/components/requestBodies/callbackMessage3' responses: '200': description: OK /unsubscribe: post: operationId: unsubscribeOperation parameters: - in: query name: Id required: true schema: type: string responses: '200': description: OK
/subscribe
エンドポイントの POST
メソッドの 200 応答のリンクは、メソッドのドキュメントの最下部に表示されます。
/subscribe
エンドポイントの POST
メソッドの 402 応答のリンクは、メソッドのドキュメントの最下部に表示されます。
コールアウト 3 ~ 5 のドキュメントは、/subscribe
エンドポイントの POST
メソッドのドキュメントの [Callbacks (コールバック)] セクションに表示されます。