README.md 6.22 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
# 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
19
  └─ index.js
Alex Quispe's avatar
Alex Quispe committed
20
21
22
23
24
25
```

### Archivo `index.js`

```js
const ApiGen = require('apidoc-generator')
26
const path   = require('path')
Alex Quispe's avatar
Alex Quispe committed
27
28
29
30
31
32
33
34

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

35
36
37
38
39
40
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
41
42
43
44
45
46
### Archivo `src/auth.js`

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

module.exports = async () => {
47
48
  await ApiGen.post('/api/auth/signin').inputData({ body: { user: 'demo1', password: 'Developer' } }).generate()               // Sin verificar
  await ApiGen.post('/api/auth/signin').inputData({ body: { user: 'demo1', password: 'Developer' } }).request(true).generate() // Verifica la ruta
Alex Quispe's avatar
Alex Quispe committed
49
50
51
}
```

52
53
La propiedad `request(true)` indica si se va a ejecutar la petición, en tal caso se documenta el resultado de la petición automáticamente.

Alex Quispe's avatar
Alex Quispe committed
54
55
56
57
58
59
### Archivo `src/api.js`

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

module.exports = async () => {
60
  const login = await ApiGen.post('/api/auth/signin').inputData({ body: { user: 'demo1', password: 'Developer' } }).execute()
Alex Quispe's avatar
Alex Quispe committed
61
62
63

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

64
  await ApiGen.get('/api/v1/instituciones').inputData({ headers: AUTH_HEADER }).request(true).generate('CUSTOM GROUP')
Alex Quispe's avatar
Alex Quispe committed
65
66
67
68
69
70
71
72
73
74
75
76
77
78
}
```

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

79
80
81
82
83
84
85
86
87
88
### 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
89
90
### Funciones disponibles:

91
92
93
94
95
96
97
98
99
100
101
102
103
| Función          | Descripción                                                            | Valor por defecto       |
| ---------------- | ---------------------------------------------------------------------- | ----------------------- |
| `name`           | Nombre con el que se identificará a la ruta.                           | `<method>/<path></key>` |
| `group`          | Grupo al que pertenece la ruta.                                        | `<fileName>`            |
| `description`    | Descripción de la ruta.                                                | `null`                  |
| `version`        | Versión.                                                               | `1`                     |
| `permissions`    | Lista de los roles. Ej.: `.permissions(['admin', 'user'])`             | `null`                  |
| `request`        | Indica si se va a ejecutar la petición para crear los datos de salida. | `false`                 |
| `key`            | Palabra clave que se adiciona al final del nombre de la ruta.          | `null`                  |
| `inputData`      | Datos de entrada: `{ headers: {}, params: {}, query: {}, body: {} }`   | `{}`                    |
| `outputData`     | Datos de salida: `body`                                                | `{}`                    |
| `inputExamples`  | Ejemplos de datos de entrada: `{ title: '', data: obj }`               | `null`                  |
| `outputExamples` | Ejemplos de datos de salida: `{ title: '', data: obj }`                | `null`                  |
Alex Quispe's avatar
Alex Quispe committed
104
105
106
107

**Ejemplo:**

```js
108
await ApiGen.get('/api/v1/users').generate()
109
110
await ApiGen.post('/api/v1/users').inputData({ body; { user: 'admin', pass: '123'} }).generate()
await ApiGen.post('/api/v1/users').inputData({ body; { user: 'admin', pass: '123'} }).name('Autenticar').generate()
111

112
113
await ApiGen.get('/api/v1/users').key('Admin').generate()
await ApiGen.get('/api/v1/users').key('User').generate()
114

115
await ApiGen.get('/ruta/verificada').request(true).generate()
Alex Quispe's avatar
Alex Quispe committed
116
117
118
119
120
121
122
123
124
125
126
127
128
```

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

129
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
130
131
132
133
134
135
136

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

137
138
// group = Auth
await ApiGen.get('/api/v1/users').generate('Auth')
Alex Quispe's avatar
Alex Quispe committed
139

140
// Devuelve el resultado de la petición (body)
Alex Quispe's avatar
Alex Quispe committed
141
142
const body = await ApiGen.get('/api/v1/users').generate()
```
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191

## Configuración de los script de ejecución

Cada fichero se ejecuta de manera independiente.

Para el archivo `documentation/generate.js`

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

ApiGen.API_URL         = 'http://localhost:4000'
ApiGen.DOC_SERVER_PORT = 5000
ApiGen.BUILD_PATH      = path.resolve(__dirname, 'build')
ApiGen.SRC_PATH        = path.resolve(__dirname, 'src')
ApiGen.HELP_TYPE       = 'YAML'  // YAML o JSON
ApiGen.DESCRIPTION     = 'Descripción general del Apidoc'

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

Para el archivo `documentation/scaffold.js`

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

ApiGen.SRC_PATH = path.resolve(__dirname, 'src')
ApiGen.HELP_TYPE = 'YAML' // YAML o JSON

const app = require('../src/app')

ApiGen.scaffold(app)
```

Para el archivo `documentation/server.js`

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

ApiGen.DOC_SERVER_PORT = 5000
ApiGen.BUILD_PATH      = path.resolve(__dirname, 'build')

const SWAGGER_JSON_URL = `http://localhost:${ApiGen.DOC_SERVER_PORT}/swagger.json`
ApiGen.REDIRECT_PATH   = `/swagger?url=${SWAGGER_JSON_URL}`

ApiGen.server()
```