Differences for OAS 3.0 in Rendered Documentation

The right pane of the text editor in API Designer displays the documentation that is written into API specifications. Documentation is rendered identically for REST API specifications written in RAML or OAS 2.0. However, documentation for API specifications written in OAS 3.0 can include multiple server definitions as well as links and callbacks.

Documentation for Definitions of Multiple Servers

OAS 3.0 enables you to define servers by using the servers field. You can define servers globally at the top of a specification, locally for endpoints, and locally for methods. Local definitions override the definitions set at the next higher level in the specification’s hierarchy. Definitions set locally for methods override definitions set at endpoints and globally. Definitions set locally for endpoints override definitions set globally.

The following example API specification demonstrates different ways, indicated by ten callouts (1-10), that you can set server definitions. After the example API specification, the documentation for the portion of the API at each callout is illustrated with a screenshot.

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

The Summary page of the documentation for this API lists the four servers that are defined in this servers field:
The /default endpoint does not override the base servers definition at the top of the API. On the Overview page for the endpoint, you can select a server to see the URI for this endpoint at that server:
The GET method for the /default endpoint also inherits the four servers in the base servers definition. On the page for this method, you can select a server to see the URI for this method at that server:
The /duplicated endpoint overrides the base servers definition, its local servers definition including only the last two servers of the original four. On the Overview page for the endpoint, you can select a server to see the URI for this endpoint at that server:
The GET method for the /duplicated endpoint inherits the two servers in the local servers definition. On the page for this method, you can select a server to see the URI for this method at that server:
The /files endpoint overrides the base servers definition, its local servers definition including only one server. On the Overview page for this endpoint, there are no servers to choose from, as there were for the previous two endpoints:
The GET method for the /files endpoint inherits the one server in the local servers definition. On the page for this method, there is no list of servers to choose from:
The /ping endpoint overrides the base servers definition, its local servers definition including only one server. On the Overview page for this endpoint, there are no servers to choose from:
The GET method for the /ping endpoint overrides both the base servers definition and the /ping endpoint’s local servers definition. The GET method’s local servers definition includes two servers. On the page for this method, you can select a server to see the URI for this method at that server:
The POST method for the /ping endpoint inherits the one server in the /ping endpoint’s local servers definition. On the Overview page for this endpoint, there is no list of servers to choose from:

Documentation for Links and Callbacks

OAS 3.0 enables you to define links and callbacks. For an explanation of these features, see the specification for openAPI 3.0 at https://swagger.io/.

The following example API specification demonstrates how to set links and callbacks. The callouts indicate parts of the API specification that are rendered as documentation in the screenshots that follow.

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

The links for the 200 response for the POST method of the /subscribe endpoint appear at the bottom of the method’s documentation:
The links for the 402 response for the POST method of the /subscribe endpoint appear at the bottom of the method’s documentation:

The documentation for callouts 3-5 appear in the Callbacks section of the documentation for the POST method of the /subscribe endpoint:

A list of API calls, including parameters, body, and responses.