Ejemplo de OpenAPI
Visualiza un endpoint generado en vivo desde OpenAPI y aprende cómo Jamdesk renderiza solicitudes, respuestas y autenticación desde tu spec.
Crear un nuevo ticket para un problema o solicitud de un cliente.
Body
customer_idstringrequiredIdentificador del cliente en Acme.
subjectstringrequiredResumen breve del problema.
priority"low" | "normal" | "high" | "urgent""low" | "normal" | "high" | "urgent"tagsarray<string>messagestringrequiredDescripción detallada del problema.
Response
Ticket creado
idstringcustomer_idstringsubjectstringprioritystringstatus"open" | "pending" | "resolved""open" | "pending" | "resolved"tagsarray<string>messagestringcreated_atstring<date-time>updated_atstring<date-time>Esta página muestra un endpoint en vivo generado a partir de una especificación OpenAPI. El esquema de solicitud, los modelos de respuesta y los ejemplos de código del panel derecho se generan automáticamente desde el spec, sin necesidad de redacción manual.
Este ejemplo usa la API de soporte de Acme. Actualiza api.openapi en tu docs.json para apuntar a tu propio archivo spec y generar endpoints reales.
¿Documentación en varios idiomas? Proporciona un archivo <spec>.<lang>.<ext> junto a tu spec fuente (p. ej., example-api.fr.yaml) y Jamdesk renderiza la versión traducida cuando los usuarios visitan la página bajo /fr/.... Consulta Traducir specs de OpenAPI.
Esta página tiene el API Playground habilitado. Haz clic en Try it en el endpoint anterior para probar la API en vivo.
Qué se genera
Con una sola línea openapi en el frontmatter, Jamdesk genera automáticamente:
- Un badge de endpoint que muestra el método y la ruta con codificación de color
- Documentación de parámetros de ruta, consulta, cabecera y cuerpo
- Esquemas de solicitud y respuesta, incluidos objetos anidados y arrays
- Ejemplos de código en cURL, Python, JavaScript, Go, Ruby, C#, Java, Rust y PHP (configurable mediante
api.examples.languages) - Detalles de autenticación extraídos de los esquemas de seguridad del spec
Todas las referencias $ref en tu spec se resuelven automáticamente, por lo que puedes organizar los esquemas con components/schemas de la forma habitual.
Configurar OpenAPI
Coloca tu spec OpenAPI 3.x (YAML o JSON) en el directorio openapi/, regístralo en docs.json bajo api.openapi y agrega openapi: /openapi/your-spec.yaml METHOD /path al frontmatter de cualquier página. Consulta la guía de configuración de OpenAPI para más detalles.
¿Escribes tu spec en YAML? Ejecútalo a través del Validador de YAML gratuito para detectar errores de indentación y sintaxis antes de que el build lo procese.