README.md 4.32 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
# 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')
27
const path   = require('path')
Alex Quispe's avatar
Alex Quispe committed
28
29
30
31
32
33
34
35

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) })
```

36
37
38
39
40
41
También es posible indicar el orden de los ficheros:

```js
ApiGen.create(['auth', 'api']).catch(e => { console.log(e) })
```

Alex Quispe's avatar
Alex Quispe committed
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
### 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

77
78
79
80
81
82
83
84
85
86
### Métodos soportados:

```js
await ApiGen.get('api/v1/users').generate()
await ApiGen.post('api/v1/users').generate()
await ApiGen.put('api/v1/users/:id').generate()
await ApiGen.patch('api/v1/users/:id').generate()
await ApiGen.delete('api/v1/users/:id').generate()
```

Alex Quispe's avatar
Alex Quispe committed
87
88
### Funciones disponibles:

89
| Función       | Descripción                                                            | Valor por defecto       |
90
91
92
93
94
95
96
97
98
| ------------- | ---------------------------------------------------------------------- | ----------------------- |
| `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
99
100
101
102

**Ejemplo:**

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

107
108
await ApiGen.get('/api/v1/users').key('Admin').generate()
await ApiGen.get('/api/v1/users').key('User').generate()
109

110
await ApiGen.get('/documentando/solo/la/ruta').request(false).generate()
Alex Quispe's avatar
Alex Quispe committed
111
112
113
114
115
116
117
118
119
120
121
122
123
```

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

124
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
125
126
127
128
129
130
131
132
133
134

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

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