README.md 2.93 KB
Newer Older
Alex Quispe's avatar
Alex Quispe committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
# Apidoc Generator

Genera la documentación de un servicio web RESTFull para ApidocJS y Swagger

La documentación se genera a partir de las respuestas que devuelve el servicio.

## Requisitos:

Para generar el APIDOC, el servicio debe estar activo en modo `development` y con datos de prueba (seeders).

## Estructura de los ficheros para su documentación

```txt
documentation
  ├─ build
  ├─ src
  │     ├─ api.js
  │     └─ auth.js
  ├─ index.js
  └─ swagger-server.js
```

### Archivo `index.js`

```js
const ApiGen = require('apidoc-generator')
const path            = require('path')

ApiGen.API_URL    = 'http://localhost:3000'
ApiGen.SRC_PATH   = path.resolve(__dirname, 'src')
ApiGen.BUILD_PATH = path.resolve(__dirname, 'build')

ApiGen.create().catch(e => { console.log(e) })
```

### Archivo `src/auth.js`

```js
const ApiGen = require('apidoc-generator')

module.exports = async () => {
  await ApiGen.post('/api/auth/signin').data({ body: { user: 'demo1', password: 'Developer' } }).generate()
}
```

### Archivo `src/api.js`

```js
const ApiGen = require('apidoc-generator')

module.exports = async () => {
  const login = await ApiGen.post('/api/auth/signin').data({ body: { user: 'demo1', password: 'Developer' } }).execute()

  const AUTH_HEADER = { Authorization: `Bearer ${login.token}` }

  await ApiGen.get('/api/v1/instituciones').data({ headers: AUTH_HEADER }).generate('CUSTOM GROUP')
}
```

## Modo de uso

`node index.js`

El resultado se encuentra en la carpeta `build`

- Apidoc compilado: `build/apidoc`
- Json Swagger: `build/apidoc/swagger.json`

## Documentación

### Funciones disponibles:

| propiedad | Descripción |
| --------- | ----------- |
| `data`    | Datos de entrada: `{ headers: {}, params: {}, query: {}, body: {} }` |
| `name`    | Nombre con el que se identificará a la ruta. |
| `description` | Descripción de la ruta |
| `group` | Grupo al que pertenece la ruta |
| `version` | Versión |
| `permissions` | Lista de los roles que pueden acceder a la ruta. Ej.: `.permissions(['admin', 'user'])` |

**Ejemplo:**

```js
ApiGen.get('/api/v1/users').generate()
ApiGen.post('/api/v1/users').data({ body; { user: 'admin', pass: '123'} }).generate()
ApiGen.post('/api/v1/users').data({ body; { user: 'admin', pass: '123'} }).name('Autenticar').generate()
```

### Función `execute`

Ejecuta la petición y devuelve el resultado del body.

```js
// Devuelve una lista de usuarios
const usuarios = await ApiGen.get('/api/v1/users').execute()
```

### Función `generate`

Ejecuta la petición, genera el respectivo apidoc y devuelve el resultado del body.

Adicionalmente se puede pasar como parámetro el nombre del grupo al que pertenece la ruta. Por defecto es el nombre del fichero.

```js
// group = <fileName>
await ApiGen.get('/api/v1/users').generate()

// group = AUTH
await ApiGen.get('/api/v1/users').generate('AUTH')

// Devuelve el resultado del body
const body = await ApiGen.get('/api/v1/users').generate()
```