mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
e3a8948aa8
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
126 lines
4.3 KiB
Plaintext
126 lines
4.3 KiB
Plaintext
---
|
|
title: "Add SDK examples"
|
|
description: "Add SDK code samples to your API documentation with the x-codeSamples OpenAPI extension or automatically with Speakeasy."
|
|
keywords: ["x-codeSamples", "SDK examples", "Speakeasy", "autogenerated SDKs"]
|
|
---
|
|
|
|
If your users interact with your API through an SDK rather than direct network requests, add SDK code samples with the `x-codeSamples` extension. Mintlify displays these samples on your OpenAPI pages.
|
|
|
|
You can write these samples yourself. If you generate your SDKs with Speakeasy, Speakeasy can add the samples to your spec automatically.
|
|
|
|
## Add examples manually
|
|
|
|
Add the `x-codeSamples` property to any request method. It has the following schema.
|
|
|
|
<ParamField body="lang" type="string" required>
|
|
The language of the code sample.
|
|
</ParamField>
|
|
|
|
<ParamField body="label" type="string">
|
|
The label for the sample. This is useful when providing multiple examples for a single endpoint.
|
|
</ParamField>
|
|
|
|
<ParamField body="source" type="string" required>
|
|
The source code of the sample.
|
|
</ParamField>
|
|
|
|
The following example shows code samples for a plant tracking app that has both a Bash CLI tool and a JavaScript SDK.
|
|
|
|
```yaml
|
|
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 });
|
|
```
|
|
|
|
## Generate examples with Speakeasy
|
|
|
|
If you generate your SDKs with [Speakeasy](https://www.speakeasy.com), you can pull its autogenerated snippets into your API reference instead of maintaining them by hand. The snippets appear in the [interactive playground](/api-playground/overview) alongside your endpoints.
|
|
|
|
<Steps>
|
|
<Step title="Get the combined spec URL from the registry">
|
|
|
|
Go to your [Speakeasy Dashboard](https://app.speakeasy.com) and open the **API Registry** tab. Open the `*-with-code-samples` entry for your API.
|
|
|
|
<Frame>
|
|
|
|
</Frame>
|
|
|
|
<Note>
|
|
If the entry is not labeled **Combined Spec**, ensure that your API has an [automated code sample URL](https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls) configured.
|
|
</Note>
|
|
|
|
From the registry entry's page, copy the provided public URL.
|
|
|
|
<Frame>
|
|
|
|
</Frame>
|
|
</Step>
|
|
<Step title="Add the combined spec URL to your `docs.json` file">
|
|
|
|
Add the combined spec URL to an anchor or a tab in the `navigation` object of your `docs.json` file.
|
|
|
|
<CodeGroup>
|
|
|
|
```json title="Anchor"
|
|
{
|
|
"navigation": {
|
|
"anchors": [
|
|
{
|
|
"anchor": "API reference",
|
|
"icon": "square-terminal",
|
|
// !mark
|
|
"openapi": "SPEAKEASY_COMBINED_SPEC_URL"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
```json title="Tab"
|
|
{
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "API reference",
|
|
// !mark
|
|
"openapi": "SPEAKEASY_COMBINED_SPEC_URL"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
</CodeGroup>
|
|
</Step>
|
|
<Step title="Verify the integration">
|
|
|
|
After you redeploy your documentation, open any endpoint in your API reference and confirm that language snippets appear in the playground. The set of available languages matches the SDK targets configured in your Speakeasy project.
|
|
|
|
If snippets do not appear, check that:
|
|
|
|
- The `openapi` URL in `docs.json` points to the `*-with-code-samples` combined spec entry, not the source OpenAPI file.
|
|
- The combined spec URL is publicly reachable from the browser.
|
|
- Your Speakeasy project has an [automated code sample URL](https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls) configured and at least one SDK target enabled.
|
|
|
|
</Step>
|
|
</Steps>
|