# Documenta tus APIs con apidoc

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.

```bash
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.

```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.
    

```python
"""
@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](https://apidocjs.com/#param-api-body).
    

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

```python
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

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1679085075395/15609ce5-c36d-4f9d-90b4-926344c648d1.png align="center")

Y se veria el sitio que nos genera `apidoc`

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1679085195016/21283ced-2f52-49fe-9714-6274b5ad6fdc.png align="center")

`apidoc` tiene muchas mas opciones para documentar errores, headers, versiones, etc. Puedes consultar la documentacion completa en el [sitio oficial](https://apidocjs.com/).