Add SDK examples

If your users mainly work through an SDK or a CLI, add code samples directly to the OpenAPI operation instead of forcing every example to be plain HTTP.

​

Add x-codeSamples

Attach code samples to an operation inside the spec.

paths:
  /documentations:
    get:
      summary: List documentations
      x-codeSamples:
        - lang: bash
          label: List from the CLI token
          source: |
            curl -H "Authorization: Bearer $DOCSALOT_API_TOKEN" \
              https://docsalot.dev/api/cli/v1/documentations
        - lang: javascript
          label: Fetch with the browser
          source: |
            const response = await fetch("/api/cli/v1/documentations", {
              headers: { Authorization: `Bearer ${token}` }
            });
            const data = await response.json();

Use label when you want multiple examples for the same language or endpoint.

​

Control language order

Set the preferred snippet order in layout.json.

{
  "api": {
    "examples": {
      "languages": ["curl", "javascript", "python"],
      "defaults": "required"
    }
  }
}

​

Good uses for SDK examples

• showing the same operation in HTTP, CLI, and SDK form
• giving browser-friendly examples for frontend developers
• highlighting the shortest path for the most common workflow

Keep the examples task-based. One good example per use case is more useful than a long list of near-duplicates.