README.md 3.89 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
# 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:

73
74
75
76
77
78
79
80
81
82
| Función     | Descripción                                                            | Valor por defecto |
| ------------- | ---------------------------------------------------------------------- | ----------------------- |
| `data`        | Datos de entrada: `{ headers: {}, params: {}, query: {}, body: {} }`   | `{}`                    |
| `name`        | Nombre con el que se identificará a la ruta.                           | `<method>/<path></key>` |
| `key`         | Palabra clave que se adiciona al final del nombre de la ruta.          | `null`                  |
| `description` | Descripción de la ruta.                                                | `null`                  |
| `group`       | Grupo al que pertenece la ruta.                                        | `<fileName>`            |
| `version`     | Versión.                                                               | `1`                     |
| `request`     | Indica si se va a ejecutar la petición para crear los datos de salida. | `true`                  |
| `permissions` | Lista de los roles. Ej.: `.permissions(['admin', 'user'])`             | `null`                  |
Alex Quispe's avatar
Alex Quispe committed
83
84
85
86
87
88
89

**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()
90
91
92
93
94

ApiGen.get('/api/v1/users').key('Admin').generate()
ApiGen.get('/api/v1/users').key('User').generate()

ApiGen.get('/documentando/solo/la/ruta').request(false).generate()
Alex Quispe's avatar
Alex Quispe committed
95
96
97
98
99
100
101
102
103
104
105
106
107
```

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

108
Ejecuta la petición (solamente si la propiedad `request` es igual a `true`), genera el respectivo apidoc y devuelve el resultado del body.
Alex Quispe's avatar
Alex Quispe committed
109
110
111
112
113
114
115
116
117
118

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')

119
// Devuelve el resultado de la petición (body)
Alex Quispe's avatar
Alex Quispe committed
120
121
const body = await ApiGen.get('/api/v1/users').generate()
```