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
  2. /default​ エンドポイントは、API の最上部のベース ​servers​ 定義を上書きしません。エンドポイントの [Overview (概要)] ページでは、サーバーを選択して、そのサーバーのこのエンドポイントの URI を確認できます。

    apid apic oas 3 default
  3. /default​ エンドポイントの GET メソッドは、ベース ​servers​ 定義の 4 つのサーバーも継承します。このメソッドのページでは、サーバーを選択して、そのサーバーのこのメソッドの URI を確認できます。

    apid apic oas 3 default get
  4. /duplicated​ エンドポイントは、ベース ​servers​ 定義を上書きします。そのローカル ​servers​ 定義には、元の 4 つのサーバーのうち最後の 2 つのサーバーのみが含まれます。エンドポイントの [Overview (概要)] ページでは、サーバーを選択して、そのサーバーのこのエンドポイントの URI を確認できます。

    apid apic oas 3 duplicated
  5. /duplicated​ エンドポイントの GET メソッドは、ローカル ​servers​ 定義の 2 つのサーバーを継承します。このメソッドのページでは、サーバーを選択して、そのサーバーのこのメソッドの URI を確認できます。

    apid apic oas 3 duplicated get
  6. /files​ エンドポイントは、ベース ​servers​ 定義を上書きします。そのローカル ​servers​ 定義には、1 つのサーバーのみが含まれます。このエンドポイントの [Overview (概要)] ページには、前の 2 つのエンドポイントのように選択するサーバーがありません。

    apid apic oas 3 files
  7. /files​ エンドポイントの GET メソッドは、ローカル ​servers​ 定義の 1 つのサーバーを継承します。このメソッドのページには、選択するサーバーのリストはありません。

    apid apic oas 3 files get
  8. /ping​ エンドポイントは、ベース ​servers​ 定義を上書きします。そのローカル ​servers​ 定義には、1 つのサーバーのみが含まれます。このエンドポイントの [Overview (概要)] ページには、選択するサーバーがありません。

    apid apic oas 3 ping
  9. /ping​ エンドポイントの ​GET​ メソッドは、ベース ​servers​ 定義と ​/ping​ エンドポイントのローカル ​servers​ 定義の両方を上書きします。​GET​ メソッドのローカル ​servers​ 定義には、2 つのサーバーが含まれます。このメソッドのページでは、サーバーを選択して、そのサーバーのこのメソッドの URI を確認できます。

    apid apic oas 3 ping get
  10. /ping​ エンドポイントの POST メソッドは、​/ping​ エンドポイントのローカル ​servers​ 定義の 1 つのサーバーを継承します。このエンドポイントの [Overview (概要)] ページには、選択するサーバーのリストがありません。

    apid apic oas 3 ping post

リンクとコールバックのドキュメント

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
  2. /subscribe​ エンドポイントの ​POST​ メソッドの 402 応答のリンクは、メソッドのドキュメントの最下部に表示されます。

    apid apic oas 3 links 2

コールアウト 3 ~ 5 のドキュメントは、​/subscribe​ エンドポイントの ​POST​ メソッドのドキュメントの ​[Callbacks (コールバック)]​ セクションに表示されます。

apid apic oas 3 callbacks