mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
b34afc88b6
* docs: fix es/fr/zh translation lag and add missing zh workflows redirects * docs: SEO metadata fixes and HTML entity cleanup in touched locale pages --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
130 lines
4.8 KiB
Plaintext
130 lines
4.8 KiB
Plaintext
---
|
|
title: "Agregar ejemplos de SDK"
|
|
description: "Agrega ejemplos de código de SDK a tu documentación de API con la extensión de OpenAPI x-codeSamples o automáticamente con Speakeasy."
|
|
keywords: ["x-codeSamples", "ejemplos de SDK", "Speakeasy", "SDK autogenerados"]
|
|
---
|
|
|
|
Si tus usuarios interactúan con tu API mediante un SDK en lugar de solicitudes de red directas, agrega ejemplos de código de SDK con la extensión `x-codeSamples`. Mintlify muestra estos ejemplos en tus páginas de OpenAPI.
|
|
|
|
Puedes escribir estos ejemplos tú mismo. Si generas tus SDK con Speakeasy, Speakeasy puede agregar los ejemplos a tu especificación automáticamente.
|
|
|
|
<div id="add-examples-manually">
|
|
## Agregar ejemplos manualmente
|
|
</div>
|
|
|
|
Agrega la propiedad `x-codeSamples` a cualquier método de solicitud. Tiene el siguiente esquema.
|
|
|
|
<ParamField body="lang" type="string" required>
|
|
El lenguaje del ejemplo de código.
|
|
</ParamField>
|
|
|
|
<ParamField body="label" type="string">
|
|
La etiqueta del ejemplo. Es útil cuando se proporcionan varios ejemplos para un mismo endpoint.
|
|
</ParamField>
|
|
|
|
<ParamField body="source" type="string" required>
|
|
El código fuente del ejemplo.
|
|
</ParamField>
|
|
|
|
El siguiente ejemplo muestra ejemplos de código para una aplicación de seguimiento de plantas que cuenta tanto con una herramienta CLI de Bash como con un SDK de JavaScript.
|
|
|
|
```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 });
|
|
```
|
|
|
|
<div id="generate-examples-with-speakeasy">
|
|
## Generar ejemplos con Speakeasy
|
|
</div>
|
|
|
|
Si generas tus SDK con [Speakeasy](https://www.speakeasy.com), puedes incorporar sus fragmentos autogenerados a tu referencia de API en lugar de mantenerlos manualmente. Los fragmentos aparecen en el [área de pruebas interactiva](/es/api-playground/overview) junto a tus endpoints.
|
|
|
|
<Steps>
|
|
<Step title="Obtén la URL de la especificación combinada desde el registro">
|
|
|
|
Ve a tu [Panel de Speakeasy](https://app.speakeasy.com) y abre la pestaña **API Registry**. Abre la entrada `*-with-code-samples` de tu API.
|
|
|
|
<Frame>
|
|
|
|
</Frame>
|
|
|
|
<Note>
|
|
Si la entrada no está etiquetada como **Combined Spec**, asegúrate de que tu API tenga configurada una [URL de ejemplos de código automáticos](https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls).
|
|
</Note>
|
|
|
|
Desde la página de la entrada del registro, copia la URL pública proporcionada.
|
|
|
|
<Frame>
|
|
|
|
</Frame>
|
|
</Step>
|
|
<Step title="Agrega la URL de la especificación combinada a tu archivo `docs.json`">
|
|
|
|
Agrega la URL de la especificación combinada a un anchor o a una pestaña en el objeto `navigation` de tu archivo `docs.json`.
|
|
|
|
<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="Verifica la integración">
|
|
|
|
Después de volver a desplegar tu documentación, abre cualquier endpoint en tu referencia de API y confirma que los fragmentos de lenguaje aparecen en el área de pruebas. El conjunto de lenguajes disponibles coincide con los targets de SDK configurados en tu proyecto de Speakeasy.
|
|
|
|
Si los fragmentos no aparecen, comprueba que:
|
|
|
|
- La URL `openapi` en `docs.json` apunte a la entrada de la especificación combinada `*-with-code-samples`, no al archivo OpenAPI de origen.
|
|
- La URL de la especificación combinada sea accesible públicamente desde el navegador.
|
|
- Tu proyecto de Speakeasy tenga configurada una [URL de ejemplos de código automatizados](https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls) y al menos un target de SDK habilitado.
|
|
|
|
</Step>
|
|
</Steps>
|