# Agregar ejemplos de SDK (/es/api-playground/adding-sdk-examples)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1377 · updated: 2026-09-23 -->
Related: [Configuración de referencias de SDK](/es/api-playground/sdk-reference-setup.md), [Tipos de datos complejos](/es/api-playground/complex-data-types.md), [Respuestas múltiples](/es/api-playground/multiple-responses.md), [Gestionar la visibilidad de páginas](/es/api-playground/managing-page-visibility.md), [Crear páginas de API manuales](/es/api-playground/mdx-setup.md)

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 [#agregar-ejemplos-manualmente]
</div>

Agrega la propiedad `x-codeSamples` a cualquier método de solicitud. Tiene el siguiente esquema.

<ParamField body="lang" type="string">
  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">
  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 [#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>
      ![Captura de pantalla de la página API Registry de Speakeasy. Un recuadro rojo y el número 1 destacan la pestaña API Registry, y un recuadro rojo y el número 2 destacan la entrada de la API.](/_assets/c467e4709030c41a7f746ea91cd2b5b064d6fb7135eb3278c8f61b0ae807ea1c)
    </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>
      ![Captura de pantalla que muestra la entrada del registro de la especificación combinada con la función de copiar URL destacada con un recuadro rojo.](/_assets/628f1be1cb011cd63b8245b1829129061f06283dffb5fda4c7db7bd323522a61)
    </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>
      <CodeBlockTabs defaultValue="Anchor" groupId="anchor+tab">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="Anchor">
            Anchor
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="Tab">
            Tab
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="Anchor">
          ```json  
          {
            "navigation": {
              "anchors": [
                {
                  "anchor": "API reference",
                  "icon": "square-terminal",
                  // !mark
                  "openapi": "SPEAKEASY_COMBINED_SPEC_URL"
                }
              ]
            }
          }
          ```
        </CodeBlockTab>

        <CodeBlockTab value="Tab">
          ```json  
          {
            "navigation": {
              "tabs": [
                {
                  "tab": "API reference",
                  // !mark
                  "openapi": "SPEAKEASY_COMBINED_SPEC_URL"
                }
              ]
            }
          }
          ```
        </CodeBlockTab>
      </CodeBlockTabs>
    </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>