Extension Field Registry

x-codeSamples - Provides custom code samples for an operation in one or more programming languages.

The x-codeSamples extension provides custom code samples for an API operation. Documentation tools commonly render each item as a language-specific example or tab alongside the operation, either replacing generated snippets or adding examples that use a provider’s preferred SDK, workflow, or request style.

Each code sample object includes a required lang string identifying the programming language or syntax highlighter, a required source value containing the sample code, and may include an optional label string for a display label. Some tools also accept a source value that references an external code sample file with a $ref.

The extension is commonly documented as the successor or camel-case alias of x-code-samples. This registry entry documents x-codeSamples; tooling may also support x-code-samples separately for compatibility.

It can appear as a property in the following objects: ["Operation Object"].

References:

Used by: (informational)

Schema 

{"type"=>"array", "items"=>{"type"=>"object", "required"=>["lang", "source"], "properties"=>{"lang"=>{"type"=>"string"}, "label"=>{"type"=>"string"}, "source"=>{"oneOf"=>[{"type"=>"string"}, {"type"=>"object", "required"=>["$ref"], "properties"=>{"$ref"=>{"type"=>"string"}}}]}}}}

Example 

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List pets
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl --request GET \
              --url https://api.example.com/pets \
              --header 'accept: application/json'
        - lang: JavaScript
          label: fetch
          source: |
            const response = await fetch("https://api.example.com/pets", {
              headers: { accept: "application/json" }
            });
            console.log(await response.json());
        - lang: Python
          source:
            $ref: code_samples/list_pets.py
      responses:
        "200":
          description: A list of pets.