Crear una referencia de API
Crea una referencia de API en tu centro de ayuda a partir de una especificación JSON de OpenAPI, Swagger 2.0, GraphQL SDL o introspección de GraphQL. Puedes subir un archivo, leer la especificación desde un repositorio de GitHub o obtenerla de una URL. Para crear y publicar una referencia de API necesitas una suscripción activa o en período de prueba, y los archivos de especificación deben pesar menos de 15 MB.
Añadir una referencia de API
Ve a la página Centro de ayuda en el panel de control.
En el encabezado de una sección, haz clic en el botón para añadir contenido y selecciona Crear referencia de API.
En el cuadro de diálogo Añadir referencia de API, elige una fuente: Subir un archivo, Desde GitHub o Desde una URL.
Subir un archivo de especificación
Las cargas aceptan archivos OpenAPI JSON o YAML y archivos de esquema de GraphQL con la extensión .graphql, .gql o .graphqls. Selecciona Subir un archivo y elige tu archivo de especificación.
Añadir una especificación desde una URL
Usa esta opción cuando tu especificación ya esté alojada en línea. La URL puede apuntar a un documento de OpenAPI, un archivo GraphQL SDL o un endpoint de GraphQL.
Selecciona Desde una URL.
Introduce la URL de tu especificación o endpoint de GraphQL.
Los endpoints de GraphQL necesitan tener habilitada la introspección. Las fuentes URL se actualizan automáticamente cada seis horas.
Si la URL de tu especificación proviene de Stainless, las páginas generadas pueden mostrar fragmentos de SDK.
Añadir una especificación desde GitHub
Lee directamente el archivo de especificación desde un repositorio en cada sincronización. La conexión de GitHub debe pertenecer al mismo espacio de trabajo y tener acceso al repositorio.
Selecciona Desde GitHub.
Selecciona una conexión de GitHub. Si todavía no has conectado GitHub, configúralo primero en Integración de GitHub.
Selecciona el repositorio.
De forma opcional, elige una rama o un commit. Cuando está disponible, se usa la rama de producción configurada; de lo contrario, se usa la rama predeterminada de GitHub del repositorio.
Introduce la ruta relativa al repositorio del archivo de especificación.
Haz clic en Comprobar especificación y espera a que la comprobación se complete correctamente.
La comprobación de la especificación debe completarse correctamente antes de poder crear la referencia de API desde GitHub.
Configurar y crear
Introduce un slug de URL para la referencia.
Elige si quieres usar Publicar inmediatamente.
Haz clic en Añadir referencia de API.
El procesamiento suele tardar unos segundos. Cuando la especificación está lista, aparece Tu referencia de API está lista; haz clic en Listo para terminar. Si el procesamiento falla, aparece Error de procesamiento; haz clic en Cerrar para cerrar el cuadro de diálogo.
SDK y ejemplos de código en las páginas de operaciones
Las páginas de operaciones generadas muestran ejemplos de código de tres fuentes, en este orden: ejemplos que la especificación declara con la extensión x-codeSamples, fragmentos de SDK incluidos en la extensión x-stainless-snippets (que las especificaciones generadas por Stainless incluyen en lenguajes como TypeScript, Python, Go, Java y Ruby) y ejemplos generados en lenguajes comunes como cURL, JavaScript, Python, Go y Ruby.
Ferndesk no mantiene una correspondencia entre los endpoints REST y los métodos del SDK: los ejemplos del SDK que ven los lectores son los que incluye tu especificación. Para añadir ejemplos escritos manualmente para cada operación, usa Ejemplos de código personalizados en Anular detalles de la operación.
Versiones de la API
Cada referencia de API realiza un seguimiento de una versión de la especificación, que se muestra en la vista general de la referencia. Para documentar varias versiones de la API, crea una referencia independiente para cada versión, cada una con su propia fuente; las referencias no se agrupan como versiones de la misma API.
Qué sigue
Mantén actualizada la fuente en Reemplazar la especificación de una referencia de API y Actualizar las fuentes de referencias de API, y ajusta la barra lateral y las páginas de operaciones en Personalizar una referencia de API.