Last updated

x-codeSamples

Usage

Use x-codeSamples (previously called x-code-samples) to add custom code samples in one or more languages to your operations. When specified, the code samples are rendered in the right panel of the API documentation. Add it to the operation OpenAPI object.

Field NameTypeDescription
x-codeSamples[ Code Sample Object ]A list of code samples associated with an operation.

Code Sample Object

Field NameTypeDescription
langstringCode sample language. Value should be one of the following list
labelstringCode sample label, for example Node or Python2.7, optional, lang is used by default
sourcestringCode sample source code

Examples

Specify the language of the sample, and add it directly in the OpenAPI file, as shown below:

openapi: '3.0.3'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-codeSamples:
        - lang: 'cURL'
          label: 'CLI'
          source: |
            curl --request POST \
            --url 'https://data.apiexample.com/api/example/batch_query/json?format=json' \
            --header 'content-type: application/octet-stream: ' \
            --data '{}'

Code sample object

lang: JavaScript
source: console.log('Hello World');

Include an external code file

Putting the code samples in separate files gives you the opportunity to validate and reuse the content. You can use the following $ref syntax to refer to a separate code sample file:

  x-code-samples:
    - lang: PHP
      source:
        $ref: ../code_samples/PHP/customers/post.php

In Reference docs

Code sample in the right panel