Es normal en tus proyectos tener muchas APIs y compartir con otros lo que hace cada una, qué parámetros reciben y qué resultados devuelven, hacer esto puede ser un tanto complicado, con el tiempo y conforme tu proyecto vaya creciento esto se puede convertir en una pesadilla y seguramente has visto cómo plataformas como Facebook, Spotify, Twitter, etc. Documentan sus APIs y quieras hacer algo similar. Para eso, te presento "apidoc", un módulo de NPM que te permitirá crear un sitio web con la documentación de tus APIs. Para comenzar necesitas instalar globalmente apidoc.

npm install apidoc -g

Una vez instalado para cada una de tus endpoints vas a añadir un comentario multilinea dependiendo del lenguaje que estes usando, apidoc soporta las siguientes extensiones de archivos .cs .dart .erl .go .java .js .php .py .rb .ts . En nuestro caso usaremos la sintaxis para python.

"""
@apiGroup items
@api {GET} https://fakesite.com/api/items Lista de elementos en DB
@apiQuery {String} [name] Nombre
@apiQuery {Number} age Edad
"""

• @apiGroup sirve para agrupar APIs

• @api especifica un endpoint la sintaxis es @api {metodo} url descripcion

• @apiQuery especifica un parametro query la sintaxis es @apiQuery {tipoDato} nombreParametro descripción

  Puedes ver esto mas a detalle aqui.

"""
@apiGroup items
@api {POST} https://fakesite.com/api/items Crea un nuevo registro
@apiBody {String} name Nombre
@apiBody {Number} age Edad
@apiSuccessExample {json} Success-Response:
  HTTP/1.1 200 OK
  {
    "name": "jhon doe",
    "age": 25
  }
"""

• @apiBody especifica un parametro body la sintaxis es @apiBody {tipoDato} nombreParametro descripcion'

• @apiSuccessExample muestra un ejemplo una petición correcta

  Puedes ver esto mas a detalle aqui.

Cuando tu documentación este lista puedes generar el sitio.

apidoc -i src -o apidoc

• -i directorio donde estan tus archivos

• -o directorio de salida

El resultado es este, un archivo index.html y los assets del sitio, estos los puedes poner en un servidor de archivos estaticos

Y se veria el sitio que nos genera apidoc

apidoc tiene muchas mas opciones para documentar errores, headers, versiones, etc. Puedes consultar la documentacion completa en el sitio oficial.