MDPress

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ámetroTipoObligatorioDescripción
limitenteroNoNúmero máximo de resultados por página
cursorcadenaNoCursor devuelto por la solicitud anterior

Ejemplo de solicitud

curl https://api.example.com/v1/resources

Campos de la respuesta

CampoTipoDescripción
dataarregloRecursos devueltos
next_cursorcadena o nullToken de la página siguiente

Errores

EstadoSignificadoAcción
400Entrada inválidaRevisar los parámetros
401Autenticación requeridaVerificar las credenciales
429Límite de solicitudes alcanzadoRespetar 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.