Differences for OAS 3.0 in Rendered Documentation | MuleSoft Documentation
# 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
```

  1. The Summary page of the documentation for this API lists the four servers that are defined in this `servers` field:
  2. 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:
  3. 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:
  4. 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:
  5. 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:
  6. 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:
  7. 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:
  8. 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:
  9. 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:
  10. 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
```

  1. The links for the 200 response for the `POST` method of the `/subscribe` endpoint appear at the bottom of the method’s documentation:
  2. 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: