--- schema_version: "1" id: 61674ba7701eb749150997f07f11199e3e28be778c1b7e71859b4b7425246a01 title: OAS 3.0 での表示されるドキュメントの違い collection: mulesoft version: current locale: ja-jp portal_url: https://docs.salesforce.com/mulesoft/current/ja-jp/design-center/design-documentation.md canonical_url: https://docs.mulesoft.com/jp/design-center/design-documentation source_site: docs.mulesoft.com content_type: documentation content_hash: f543cd892d2d1f677aeaf838bb4274716c69bbdb6e33ba1b07080d1b5578a6de description: MuleSoft Documentation Site latest: true --- # OAS 3.0 での表示されるドキュメントの違い API 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 1. この API のドキュメントの \[Summary (概要)\] ページには、次の ​`servers`​ 項目で定義されている 4 つのサーバーがリストされています。 ![apid apic oas 3 summary](/mulesoft/current/ja-jp/design-center/_images/apid-apic-oas-3-summary.png) 2. `/default`​ エンドポイントは、API の最上部のベース ​`servers`​ 定義を上書きしません。エンドポイントの \[Overview (概要)\] ページでは、サーバーを選択して、そのサーバーのこのエンドポイントの URI を確認できます。 ![apid apic oas 3 default](/mulesoft/current/ja-jp/design-center/_images/apid-apic-oas-3-default.png) 3. `/default`​ エンドポイントの GET メソッドは、ベース ​`servers`​ 定義の 4 つのサーバーも継承します。このメソッドのページでは、サーバーを選択して、そのサーバーのこのメソッドの URI を確認できます。 ![apid apic oas 3 default get](/mulesoft/current/ja-jp/design-center/_images/apid-apic-oas-3-default-get.png) 4. `/duplicated`​ エンドポイントは、ベース ​`servers`​ 定義を上書きします。そのローカル ​`servers`​ 定義には、元の 4 つのサーバーのうち最後の 2 つのサーバーのみが含まれます。エンドポイントの \[Overview (概要)\] ページでは、サーバーを選択して、そのサーバーのこのエンドポイントの URI を確認できます。 ![apid apic oas 3 duplicated](/mulesoft/current/ja-jp/design-center/_images/apid-apic-oas-3-duplicated.png) 5. `/duplicated`​ エンドポイントの GET メソッドは、ローカル ​`servers`​ 定義の 2 つのサーバーを継承します。このメソッドのページでは、サーバーを選択して、そのサーバーのこのメソッドの URI を確認できます。 ![apid apic oas 3 duplicated get](/mulesoft/current/ja-jp/design-center/_images/apid-apic-oas-3-duplicated-get.png) 6. `/files`​ エンドポイントは、ベース ​`servers`​ 定義を上書きします。そのローカル ​`servers`​ 定義には、1 つのサーバーのみが含まれます。このエンドポイントの \[Overview (概要)\] ページには、前の 2 つのエンドポイントのように選択するサーバーがありません。 ![apid apic oas 3 files](/mulesoft/current/ja-jp/design-center/_images/apid-apic-oas-3-files.png) 7. `/files`​ エンドポイントの GET メソッドは、ローカル ​`servers`​ 定義の 1 つのサーバーを継承します。このメソッドのページには、選択するサーバーのリストはありません。 ![apid apic oas 3 files get](/mulesoft/current/ja-jp/design-center/_images/apid-apic-oas-3-files-get.png) 8. `/ping`​ エンドポイントは、ベース ​`servers`​ 定義を上書きします。そのローカル ​`servers`​ 定義には、1 つのサーバーのみが含まれます。このエンドポイントの \[Overview (概要)\] ページには、選択するサーバーがありません。 ![apid apic oas 3 ping](/mulesoft/current/ja-jp/design-center/_images/apid-apic-oas-3-ping.png) 9. `/ping`​ エンドポイントの ​`GET`​ メソッドは、ベース ​`servers`​ 定義と ​`/ping`​ エンドポイントのローカル ​`servers`​ 定義の両方を上書きします。​`GET`​ メソッドのローカル ​`servers`​ 定義には、2 つのサーバーが含まれます。このメソッドのページでは、サーバーを選択して、そのサーバーのこのメソッドの URI を確認できます。 ![apid apic oas 3 ping get](/mulesoft/current/ja-jp/design-center/_images/apid-apic-oas-3-ping-get.png) 10. `/ping`​ エンドポイントの POST メソッドは、​`/ping`​ エンドポイントのローカル ​`servers`​ 定義の 1 つのサーバーを継承します。このエンドポイントの \[Overview (概要)\] ページには、選択するサーバーのリストがありません。 ![apid apic oas 3 ping post](/mulesoft/current/ja-jp/design-center/_images/apid-apic-oas-3-ping-post.png) ## [](#リンクとコールバックのドキュメント)リンクとコールバックのドキュメント 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 1. `/subscribe`​ エンドポイントの ​`POST`​ メソッドの 200 応答のリンクは、メソッドのドキュメントの最下部に表示されます。 ![apid apic oas 3 links 1](/mulesoft/current/ja-jp/design-center/_images/apid-apic-oas-3-links-1.png) 2. `/subscribe`​ エンドポイントの ​`POST`​ メソッドの 402 応答のリンクは、メソッドのドキュメントの最下部に表示されます。 ![apid apic oas 3 links 2](/mulesoft/current/ja-jp/design-center/_images/apid-apic-oas-3-links-2.png) コールアウト 3 ～ 5 のドキュメントは、​`/subscribe`​ エンドポイントの ​`POST`​ メソッドのドキュメントの ​**\[Callbacks (コールバック)\]**​ セクションに表示されます。 ![apid apic oas 3 callbacks](/mulesoft/current/ja-jp/design-center/_images/apid-apic-oas-3-callbacks.png)