La URL apunta a una dirección privada o interna, o redirige a una. Usa una dirección accesible para cualquier persona en internet.
Publicar una referencia de API
Convierte tu especificación de OpenAPI o GraphQL en páginas de referencia de API en tu centro de ayuda, con un entorno de pruebas donde los lectores pueden enviar solicitudes reales. Los lectores encontrarán las operaciones en las mismas búsquedas que tus artículos, y tu agente de IA podrá responder a partir de ellas.
Necesitas una suscripción activa o una prueba gratuita.
Añadir tu especificación
En Centro de ayuda, abre el menú para añadir contenido de una sección y elige Crear referencia de API. Admitimos OpenAPI (JSON o YAML), Swagger 2.0, GraphQL SDL y JSON de introspección de GraphQL, hasta 15 MB. La forma de mantenerla actualizada depende del origen de la especificación:
Origen | Cómo se mantiene actualizada |
|---|---|
Desde GitHub | Se actualiza cuando un envío modifica el archivo de especificación en la rama que elegiste. Necesitas conectar GitHub. |
Desde una URL | Volvemos a obtenerla cada seis horas. La introspección debe estar activada en los endpoints de GraphQL. |
Subir un archivo | No se actualiza por sí sola. Sube un archivo nuevo con Reemplazar especificación. |
Usa Actualizar ahora para obtener de inmediato una especificación desde una URL o GitHub, y Reemplazar especificación para cambiar a otro origen. Para documentar varias versiones de una API, añade una referencia por versión.
Configurar las páginas
Todo lo demás se configura en los ajustes de la referencia, así que no necesitas editar la especificación:
Elige cómo aparece en la barra lateral (en una lista plana, como carpetas o como una sola entrada contraída), cambia el orden de los grupos y asígnales iconos.
Oculta las operaciones, los esquemas o los tipos de GraphQL que los lectores no necesiten.
Cambia el resumen de una operación, añade notas o agrega Ejemplos de código personalizados. Estos cambios se mantienen al actualizar la especificación, siempre que la operación conserve su método y ruta.
Los ejemplos de código también pueden provenir de la propia especificación: x-codeSamples y los fragmentos del SDK en las especificaciones generadas por Stainless.
El entorno de pruebas
Los lectores pueden hacer clic en Probar en cualquier operación o usar la página del entorno de pruebas en una referencia de GraphQL para enviar una solicitud real. Las solicitudes pasan por nuestros servidores, no por el navegador del lector, así que tu API no necesita configuración de CORS. Solo pueden acceder a los servidores que aparecen en tu especificación o al endpoint de GraphQL que hayas definido, nunca a direcciones privadas o internas. Las claves y los encabezados que introduzcan los lectores se envían con su solicitud y nunca se publican junto con la referencia.
Publicar y limitar el acceso
Publica la referencia para mostrarla en tu centro de ayuda o activa Publicar inmediatamente al crearla. Anular la publicación de la referencia de API la deja fuera de línea y conserva tus ajustes. Si la eliminas, sus páginas desaparecerán definitivamente.
La referencia hereda el acceso de su sección. Para mostrarla solo a algunos clientes, colócala en una sección limitada a su grupo. Consulta Mostrar contenido a lectores específicos.
Errores del origen
Host de la URL de la especificación de API bloqueado
No se pudo resolver el host de la URL de la especificación de API
El nombre de dominio no existe. Comprueba que la URL no tenga errores tipográficos.
Solo se permiten URL HTTP(S) para especificaciones de API, y la URL no debe incluir credenciales
Usa una dirección http:// o https:// simple, sin nombre de usuario ni contraseña.
No se pudo obtener la especificación de tu host o hubo demasiadas redirecciones
Tu servidor devolvió un error o redirigió más de cinco veces. Comprueba que la URL siga sirviendo directamente la especificación.
La URL no devolvió un documento de especificación ni un esquema de GraphQL
Indica un archivo OpenAPI, un archivo GraphQL SDL o un endpoint de GraphQL con la introspección activada.
La especificación de API supera el límite de 15 MB
Reduce el tamaño de la especificación, por ejemplo, dividiéndola en una referencia por API.
No se pudo autenticar con GitHub o la conexión de GitHub no puede leer ese repositorio
Vuelve a conectar GitHub o concede a tu conexión de GitHub acceso a ese repositorio y, después, haz clic en Actualizar ahora.
La ruta de GitHub debe apuntar a un archivo, o no se encontró el archivo en el repositorio de GitHub
Comprueba que la ruta corresponda al archivo de especificación y no a una carpeta, y que el archivo exista en la rama o confirmación que elegiste.
Error de procesamiento
No pudimos leer la especificación. Corrígela y usa Reemplazar especificación para intentarlo de nuevo.