README.md 6.65 KB
Newer Older
Alex Quispe's avatar
Alex Quispe committed
1
# Agetic BPM Doc Generator
Alex Quispe's avatar
Alex Quispe committed
2

Alex Quispe's avatar
Alex Quispe committed
3
Generador de Apidoc y Test de Integración para servicios web creados con express.
Alex Quispe's avatar
Alex Quispe committed
4

Alex Quispe's avatar
Alex Quispe committed
5
## Características
Alex Quispe's avatar
Alex Quispe committed
6

Alex Quispe's avatar
Alex Quispe committed
7
8
- El servicio debe estar creado con [express](https://expressjs.com/es/).
- Utiliza [ava](https://github.com/avajs/ava) para ejecutar los tests y [ApidocJS](http://apidocjs.com/) junto con [Swagger](https://swagger.io/) para construir el apidoc.
Alex Quispe's avatar
Alex Quispe committed
9

Alex Quispe's avatar
Alex Quispe committed
10
## Interfaz de línea de comandos
11

Alex Quispe's avatar
Alex Quispe committed
12
Esta librería contiene una herramienta CLI, cuya función es generar y procesar todos los ficheros que se requieren para crear la documentación.
Alex Quispe's avatar
Alex Quispe committed
13

Alex Quispe's avatar
Alex Quispe committed
14
### Instalación
Alex Quispe's avatar
Alex Quispe committed
15

Alex Quispe's avatar
Alex Quispe committed
16
17
```bash
npm install -g git+ssh://git@gitlab.geo.gob.bo:agetic/agetic-bpm-doc-generator.git
Alex Quispe's avatar
Alex Quispe committed
18
19
```

Alex Quispe's avatar
Alex Quispe committed
20
Para verificar la instalación, ejecutar el comando: `doc --version`
21

Alex Quispe's avatar
Alex Quispe committed
22
Para ver todas las opciones disponibles: `doc --help` o `doc <comando> --help`
Alex Quispe's avatar
Alex Quispe committed
23

Alex Quispe's avatar
Alex Quispe committed
24
25
26
27
28
29
30
31
32
33
34
35
36
37
## Configuración del proyecto

Al utilizar esta herramienta, se observan las siguientes modificaciones en el proyecto:

```txt
app
  ├─ doc.json
  ├─ index.js
  └─ package.json
```

### Archivo de configuración `doc.json`

Este archivo, puede ser generado con el comando `doc init`
Alex Quispe's avatar
Alex Quispe committed
38

Alex Quispe's avatar
Alex Quispe committed
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
```json
{
  "buildPath": "doc/build",
  "testPath": "doc/test",
  "templatePath": "doc/template",
  "compilePath": "doc/public/bpm-doc",
  "helpersPath": "doc/helpers",
  "helpersType": "YAML",
  "apiUrl": "http://localhost:4000",
  "apiName": "Apidoc",
  "apiVersion": "1.0.0",
  "apiDescription": "<a href=\"../apidoc\" style=\"background-color: #0062cc;color:white;padding:10px;border-radius:20px;text-decoration:none;font-weight:bold\">APIDOC JS</a>",
  "serverPort": 5000,
  "serverPublic": "doc/public",
  "serverRedirect": "./bpm-doc/swagger",
  "appPath": "index.js"
}
```

### Archivo `package.json`

Estos datos se agregan automáticamente al ejecutar el comando `doc init`

```json
{
  "devDependencies": {
    "agetic-bpm-doc-generator": "git+ssh://git@gitlab.geo.gob.bo:agetic/agetic-bpm-doc-generator.git",
    "ava": "^0.25.0"
  }
}
```
Alex Quispe's avatar
Alex Quispe committed
70

Alex Quispe's avatar
Alex Quispe committed
71
Esta configuración es opcional, en caso de que no se tenga instalado globalmente la libreria.
Alex Quispe's avatar
Alex Quispe committed
72

Alex Quispe's avatar
Alex Quispe committed
73
74
75
76
77
78
79
80
81
82
```json
{
  "scripts": {
    "doc:routes": "NODE_ENV=test ./node_modules/.bin/doc routes",
    "doc:scaffold": "NODE_ENV=test ./node_modules/.bin/doc scaffold",
    "doc:build": "rm -rf doc/build && NODE_ENV=test ./node_modules/.bin/ava doc/test/* --serial --verbose && npm run doc:compile",
    "doc:compile": "./node_modules/.bin/doc compile",
    "doc:server": "./node_modules/.bin/doc server",
    "doc:start": "npm run doc:compile && npm run doc:server"
  }
Alex Quispe's avatar
Alex Quispe committed
83
84
85
}
```

Alex Quispe's avatar
Alex Quispe committed
86
## Proceso de creación del apidoc
Alex Quispe's avatar
Alex Quispe committed
87

Alex Quispe's avatar
Alex Quispe committed
88
89
90
```bash
# Crea el archivo de configuración
doc init
Alex Quispe's avatar
Alex Quispe committed
91

Alex Quispe's avatar
Alex Quispe committed
92
93
# Crea los ficheros base
npm run doc:scaffold
Alex Quispe's avatar
Alex Quispe committed
94

Alex Quispe's avatar
Alex Quispe committed
95
96
# Ejecuta los tests y construye los ficheros que requiere ApidocJS y Swagger.
npm run doc:build
Alex Quispe's avatar
Alex Quispe committed
97

Alex Quispe's avatar
Alex Quispe committed
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
# Compila los ficheros
npm run doc:compile

# Levanta el servidor para visualizar el apidoc
npm run doc:server

# Compila los ficheros y Levanta el servidor
npm run doc:start
```

El siguiente comando, muestra todas las rutas de la aplicación

```bash
npm run doc:routes
```
Alex Quispe's avatar
Alex Quispe committed
113

Alex Quispe's avatar
Alex Quispe committed
114
## Métodos soportados:
115
116

```js
Alex Quispe's avatar
Alex Quispe committed
117
118
119
120
121
await ApidocGenerator.get('api/v1/users').generate()
await ApidocGenerator.post('api/v1/users').generate()
await ApidocGenerator.put('api/v1/users/:id').generate()
await ApidocGenerator.patch('api/v1/users/:id').generate()
await ApidocGenerator.delete('api/v1/users/:id').generate()
122
123
```

Alex Quispe's avatar
Alex Quispe committed
124
125
### Funciones disponibles:

126
127
128
129
130
131
132
133
134
| 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`                  |
Alex Quispe's avatar
Alex Quispe committed
135
136
| `inputData`      | Datos de entrada: `{ headers: {}, params: {}, query: {}, body: {} }`   | `null`                  |
| `outputData`     | Datos de salida: `body`                                                | `null`                  |
137
138
| `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
139
140
141
142

**Ejemplo:**

```js
Alex Quispe's avatar
Alex Quispe committed
143
144
145
await ApidocGenerator.get('/api/v1/users').generate()
await ApidocGenerator.post('/api/v1/users').inputData({ body; { user: 'admin', pass: '123'} }).generate()
await ApidocGenerator.post('/api/v1/users').inputData({ body; { user: 'admin', pass: '123'} }).name('Autenticar').generate()
146

Alex Quispe's avatar
Alex Quispe committed
147
148
await ApidocGenerator.get('/api/v1/users').key('Admin').generate()
await ApidocGenerator.get('/api/v1/users').key('User').generate()
149

Alex Quispe's avatar
Alex Quispe committed
150
await ApidocGenerator.get('/ruta/verificada').request(true).generate()
Alex Quispe's avatar
Alex Quispe committed
151
152
153
154
155
156
157
```

### Función `execute`

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

```js
Alex Quispe's avatar
Alex Quispe committed
158
159
160
// Inicializa el objeto
ApidocRequest.init()

Alex Quispe's avatar
Alex Quispe committed
161
// Devuelve una lista de usuarios
Alex Quispe's avatar
Alex Quispe committed
162
const usuarios = await ApidocRequest.get('/api/v1/users').execute()
Alex Quispe's avatar
Alex Quispe committed
163
164
165
166
```

### Función `generate`

Alex Quispe's avatar
Alex Quispe committed
167
Ejecuta una consulta (solamente si la propiedad `request` es igual a `true`), genera el respectivo apidoc y devuelve el resultado de la consulta.
168

169
```js
Alex Quispe's avatar
Alex Quispe committed
170
await ApidocGenerator.get('/api/v1/users').generate()
171

Alex Quispe's avatar
Alex Quispe committed
172
173
174
175
// Devuelve el resultado de la petición
const response = await ApidocGenerator.get('/api/v1/users').generate()
const error = response.error
const body  = response.body
176
177
```

Alex Quispe's avatar
Alex Quispe committed
178
### Flujo de ejecución
Alex Quispe's avatar
Alex Quispe committed
179

Alex Quispe's avatar
Alex Quispe committed
180
#### ApidocGenerator
181

Alex Quispe's avatar
Alex Quispe committed
182
183
184
185
186
187
1. Definición de la ruta (method, path)
- Carga la configuración global a nivel de archivo [automático cuando se define la ruta]
- Carga los helpers (propiedades estáticas) [automático cuando se define la ruta]
- Asignación de datos
- generate: Completa los datos faltantes con sus valores por defecto
- generate: Si request === true, ejecuta la petición y actualiza la propiedad output.
188

Alex Quispe's avatar
Alex Quispe committed
189
#### ApidocRequest
190

Alex Quispe's avatar
Alex Quispe committed
191
192
193
194
1. Definición de la ruta (method, path)
- Carga los helpers (propiedades estáticas) [manual llamando al método `.loadHelp(groupName)`]
- Asignación de datos
- execute: Ejecuta la petición con los datos actuales