mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
e418011c0f
- Updated api-playground/adding-sdk-examples.mdx Mintlify-Source: dashboard-editor
53 lines
2.3 KiB
Plaintext
53 lines
2.3 KiB
Plaintext
---
|
|
title: "Add SDK examples"
|
|
description: "Add SDK code samples to your API documentation with autogenerated examples from Speakeasy and Stainless across multiple languages."
|
|
keywords: ["x-codeSamples", "SDK examples"]
|
|
---
|
|
|
|
SDKs (software development kits) are language-specific libraries that wrap your API, giving developers idiomatic methods, typed responses, and built-in handling for authentication, retries, and errors. Instead of constructing raw HTTP requests, users call functions in their preferred language, which makes integrations faster to build and easier to maintain.
|
|
|
|
If your users interact with your API through an SDK rather than direct network requests, use the `x-codeSamples` extension to add code samples to your OpenAPI document. Mintlify displays the samples on your OpenAPI pages alongside the default request examples, so users can copy code in the language they actually use.
|
|
|
|
Common tools for generating and maintaining SDKs include [Speakeasy](https://www.speakeasy.com/) and [Stainless](https://www.stainless.com/), which can produce SDKs and matching `x-codeSamples` from your OpenAPI document.
|
|
|
|
Add this 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>
|
|
|
|
Here is an example of code samples for a plant tracking app, which 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 });
|
|
``` |