Code samples

Every operation shows a request sample in the right column. OrbitDocs generates it in 10 languages from the spec. You can add your own samples, and orbitdocs sdk can add a sample for each SDK it builds.

Generated samplesCopy Anchor Link

The first five appear as tabs in the Client Libraries card; the rest are under More. Each operation's sample card has a language menu with all of them.

What a sample containsCopy Anchor Link

Samples are built from the operation's examples, so they run as shown:

• URL. The first server in servers, plus the path. Path parameters use their example, default or first enum value.
• Query and headers. Required ones always, optional ones only when they have an example. This keeps samples short.
• Body. The request body's example. Without one, an example is generated from the schema. Multipart bodies list each field; file fields become a file upload.
• Auth. A placeholder for the operation's security scheme: YOUR_API_KEY, Bearer YOUR_TOKEN or a Basic header. When a reader enters a credential, it replaces the placeholder. See Authentication.

The reader's languageCopy Anchor Link

The language a reader picks applies to every operation and is remembered in their browser. To keep pages small, each page carries one sample per operation. When a reader picks another language, the samples for every operation load once from /reference-samples/<api id>.json.

Add your own samplesCopy Anchor Link

Hand-written samples come first, before the generated ones. In a Nest app, use @DocsSamples:

@Post()
@DocsOperation({ group: 'Bookings', title: 'Create a booking', order: 1 })
@DocsSamples([
  {
    lang: 'typescript',
    label: 'TypeScript SDK',
    source: [
      'const booking = await orbit.bookings.create({',
      "  flightId: 'flt_2031_proxima',",
      "  cabin: 'economy',",
      "  passengers: [{ name: 'Ada Lovelace', email: 'ada@example.com' }],",
      '});',
    ].join('\n'),
  },
])
create(@Body() dto: CreateBookingDto) {}

In a spec file, use the x-codeSamples extension on the operation. x-code-samples also works:

paths:
  /invoices:
    post:
      operationId: createInvoice
      x-codeSamples:
        - lang: typescript
          label: TypeScript SDK
          source: |
            const invoice = await billing.invoices.create({ customerId: 'cus_42' });

SDK samplesCopy Anchor Link

When you generate SDKs with orbitdocs sdk, it also writes a sample per operation for each SDK to .orbitdocs/sdk-samples.json. The reference adds them as samples labeled TypeScript SDK, Python SDK, Go SDK, Java SDK, C# SDK and PHP SDK.

sdks: {
  typescript: { package: '@orbit-travel/sdk' },
  python: { package: 'orbit_travel' },
  samples: true, // the default; false keeps SDK samples out of the reference
},

A hand-written sample with the same label wins over the generated SDK sample. See SDK samples.

Samples in the API clientCopy Anchor Link

The API client's Code tab generates a snippet for the request as you edited it, with your variables resolved. It offers cURL, JavaScript, Node.js, Python, Go, PHP, Ruby and C#. See Requests.

Next stepsCopy Anchor Link