Skip to main content
If your users interact with your API using an SDK rather than directly through a network request, you can use the x-codeSamples extension to add code samples to your OpenAPI document and display them in your OpenAPI pages. SDK examples appear alongside the default cURL examples in your API playground, making it easier for developers to integrate with your API using their preferred language or framework. This property can be added to any request method and has the following schema.
​
lang
string
required
The language of the code sample.
​
label
string
The label for the sample. This is useful when providing multiple examples for a single endpoint.
​
source
string
required
The source code of the sample.
Here is an example of code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK. 
paths:
  /plants:
    get:
      # ...
      x-codeSamples:
        - lang: bash
          label: List all unwatered plants
          source: |
            planter list -u
        - lang: javascript
          label: List all unwatered plants
          source: |
            const planter = require('planter');
            planter.list({ unwatered: true });
        - lang: bash
          label: List all potted plants
          source: |
            planter list -p
        - lang: javascript
          label: List all potted plants
          source: |
            const planter = require('planter');
            planter.list({ potted: true });

​
Multiple SDK languages

You can provide examples in multiple programming languages to support different developer audiences. Common languages include: 
x-codeSamples:
  - lang: python
    label: Get user by ID
    source: |
      import requests
      
      response = requests.get(
          'https://api.example.com/users/123',
          headers={'Authorization': 'Bearer YOUR_TOKEN'}
      )
      user = response.json()

​
Best practices

Provide examples that reflect actual use cases rather than placeholder code. Include error handling and common patterns your users will need.
Focus on the essential code needed to make the API call. Avoid unnecessary boilerplate that distracts from the core functionality.
If you provide official SDKs, ensure the examples match your SDK’s actual API and conventions. Keep examples updated when your SDK changes.
Show how to properly authenticate requests in each language, as authentication patterns vary significantly across SDKs.
Use descriptive labels when providing multiple examples for the same endpoint to help users find the right example quickly.

Learn more about OpenAPI setup

Configure OpenAPI specifications and generate API documentation