Documentación de APIs

{ "status": 202, "message": "Accepted", "description": "La documentación de la API está siendo generada. Por favor, inténtelo de nuevo más tarde. Estamos trabajando activamente en ello." }

Como puedes ver en el estado de arriba, la documentación está "en el horno". Mientras se cocina a fuego lento, hemos pensado que sería divertido compartir algunas de las notas y el caos controlado que hay detrás de la creación de una buena API. Considera esto la sección de "escenas eliminadas".

Roadmap (o más bien, servilleta con garabatos) para la Documentación de la API

# /project-docs/TODO.yml

version: 0.1-alpha
status: "NeedsMoreCoffee"
tasks:
  - id: write_intro
    status: InProgress
    assignee: "El único dev que quedaba"
    notes: "¿Cómo empiezo esto? ¿'Hola, mundo de la API'?"

  - id: explain_auth_endpoint
    status: Blocked
    blocker: "Se me olvidó cómo funciona el OAuth2. Otra vez."
    notes: "Preguntar a Stack Overflow y rezar."

  - id: add_code_examples
    status: Pending
    notes: "Primero necesito que los otros endpoints funcionen."

  - id: review_and_publish
    status: Blocked
    blocker: "El síndrome de la página en blanco es real."
    deadline: "Cuando esté listo™"

• uncionalidades que la documentación SÍ tendrá (eventualmente): ✅ Ejemplos de código que podrás copiar y pegar sin que explote todo (lo prometemos). ✅ Explicaciones de los códigos de error que no sean simplemente Error 400: "Algo salió mal". ✅ Una sección "Guía de Inicio Rápido" para los impacientes. ❌ Chistes malos. Bueno, quizá solo algunos.
• Bromas aparte, nos tomamos esta sección muy en serio. Creemos firmemente que una API es tan buena como la calidad de su documentación. Por eso, estamos invirtiendo el tiempo necesario para construir una guía que sea realmente útil: clara, completa y con ejemplos prácticos que te ahorren tiempo. Mientras tanto, si tienes cualquier duda técnica o necesitas ayuda para empezar, no dudes en ponerte en contacto con nosotros a través de la sección de Contacto. Estamos aquí para ayudarte directamente. Gracias por tu paciencia, estamos construyendo algo grande para ti.