Desarrollo
Plantilla de documentación de API en Markdown
Una buena documentación de API permite que un desarrollador haga su primera solicitud exitosa en minutos. Esta plantilla presenta un endpoint de principio a fin para que copies el patrón en el resto: descripción general, autenticación, parámetros, un ejemplo de solicitud, campos de respuesta, errores y un contacto de soporte.
Abrir esta plantilla en el editor- Categoría
- Desarrollo
- Estilo predeterminado
- Técnico
Cuándo usarla
Recurre a ella cuando un socio, un cliente o un equipo interno necesite una referencia que pueda leer sin conexión, adjuntar a un contrato o guardar junto con una versión. Tus lectores son desarrolladores que copiarán desde la página, así que el PDF conserva el texto seleccionable y los ejemplos de código mantienen su formato.
Qué incluye
- Secciones de descripción general y autenticación, con campos para completar el proyecto, la persona responsable, la fecha y el correo de soporte.
- Una entrada de endpoint con una tabla de parámetros que muestra tipo, si es obligatorio y descripción, además de un ejemplo con curl.
- Una tabla de campos de respuesta y una tabla de errores con el estado, su significado y la acción a seguir.
Consejos para un mejor documento
- Usa tokens de ejemplo en cada muestra y nunca una clave real. Indica el lenguaje en cada bloque de código para que MDPress aplique el resaltado de sintaxis.
- Cuando documentes más de unos pocos endpoints, activa el índice con números de página para que los lectores salten directo al que necesitan.
Vista previa de la plantilla
Referencia de API de Proyecto o tema
Responsable: Tu nombre · Actualizado: Fecha
Descripción general
Explica el propósito de la API, la URL base y la versión.
Autenticación
Describe cómo obtener un token y enviarlo de forma segura. Usa valores de ejemplo en los ejemplos.
Listar recursos
GET /v1/resources
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| limit | entero | No | Número máximo de resultados por página |
| cursor | cadena | No | Cursor devuelto por la solicitud anterior |
Ejemplo de solicitud
curl https://api.example.com/v1/resources
Campos de la respuesta
| Campo | Tipo | Descripción |
|---|---|---|
| data | arreglo | Recursos devueltos |
| next_cursor | cadena o null | Token de la página siguiente |
Errores
| Estado | Significado | Acción |
|---|---|---|
| 400 | Entrada inválida | Revisar los parámetros |
| 401 | Autenticación requerida | Verificar las credenciales |
| 429 | Límite de solicitudes alcanzado | Respetar el tiempo de espera indicado |
Soporte
Correo electrónico
Los campos por completar, como tu nombre y la fecha, se sustituyen cuando abres la plantilla en el editor.