--- schema_version: "1" id: 5800c1bc3c2dc02a3aafdc6ab6d2194cd98863249e47a2700c8388a402d5267e title: Differences for OAS 3.0 in Rendered Documentation collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/design-center/design-documentation.md canonical_url: https://docs.mulesoft.com/design-center/design-documentation source_site: docs.mulesoft.com content_type: documentation content_hash: a800090dcde134416d04b71503cea819de3209989c4d34badee6e47689c8cb0e description: MuleSoft Documentation Site latest: true --- --- product: Design Center --- # Differences for OAS 3.0 in Rendered Documentation > For the full documentation index, see: https://docs.mulesoft.com/llms.txt 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: ![A list of API servers and endpoints with their available methods.](/mulesoft/current/en-us/design-center/_images/apid-apic-oas-3-summary.png) 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: ![A dialog box with a server selection dropdown and a GET button.](/mulesoft/current/en-us/design-center/_images/apid-apic-oas-3-default.png) 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: ![An API documentation page with code examples and responses.](/mulesoft/current/en-us/design-center/_images/apid-apic-oas-3-default-get.png) 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: ![A dropdown menu for choosing your server.](/mulesoft/current/en-us/design-center/_images/apid-apic-oas-3-duplicated.png) 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: ![An API documentation page demonstrating the GET method for duplicate data.](/mulesoft/current/en-us/design-center/_images/apid-apic-oas-3-duplicated-get.png) 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: ![An API documentation page with instructions for file upload and download actions.](/mulesoft/current/en-us/design-center/_images/apid-apic-oas-3-files.png) 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: !["An API documentation page illustrating the GET method for file retrieval](/mulesoft/current/en-us/design-center/_images/apid-apic-oas-3-files-get.png) 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: ![An arrow points to a URL.](/mulesoft/current/en-us/design-center/_images/apid-apic-oas-3-ping.png) 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: !["A form with a server selection dropdown](/mulesoft/current/en-us/design-center/_images/apid-apic-oas-3-ping-get.png) 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: ![a code snippet that demonstrates the post method for /ping.](/mulesoft/current/en-us/design-center/_images/apid-apic-oas-3-ping-post.png) ## 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: !["Two tables with variable and expression columns.](/mulesoft/current/en-us/design-center/_images/apid-apic-oas-3-links-1.png) 2. The links for the 402 response for the `POST` method of the `/subscribe` endpoint appear at the bottom of the method’s documentation: ![A table that displays variables and their expressions.](/mulesoft/current/en-us/design-center/_images/apid-apic-oas-3-links-2.png) 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.](/mulesoft/current/en-us/design-center/_images/apid-apic-oas-3-callbacks.png)