Commit e3a1d10e authored by Alex Quispe's avatar Alex Quispe
Browse files

Documentación actualizada

parent 4b1ec755
# Apidoc Generator
Genera la documentación de un servicio web RESTFull para ApidocJS y Swagger
Genera la documentación de un servicio web RESTFull con soporte 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
```
### 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) })
```
También es posible indicar el orden de los ficheros:
```js
ApiGen.create(['auth', 'api']).catch(e => { console.log(e) })
```
- Es posible documentar las rutas a partir de una instancia de `express`, sin necesidad de levantar el servicio.
- Si el servicio está activo en modo `development` o `test`, es posible ejecutar funciones adicionales realizando peticiones sobre el servicio, permitiendo de esa forma documentar las respuestas automaticamente.
### Archivo `src/auth.js`
......@@ -141,27 +112,35 @@ await ApiGen.get('/api/v1/users').generate('Auth')
const body = await ApiGen.get('/api/v1/users').generate()
```
## Configuración de los script de ejecución
## Configuración del proyecto para generar la documentación
Cada fichero se ejecuta de manera independiente.
Para el archivo `documentation/generate.js`
### Estructura
```js
const ApiGen = require('apidoc-generator')
const path = require('path')
```txt
app
├─ documentation
| ├─ build
| ├─ src
| │ ├─ api.js
| │ └─ auth.js
| ├─ scaffold.js
| ├─ generate.js
| └─ server.js
├─ src
│ └─ app.js
├─ index.js
└─ package.json
```
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'
### Archivo `documentation/scaffold.js`
Este fichero se encarga de crear los ficheros necesarios para documentar las rutas:
ApiGen.create().catch(e => console.log(e))
```
- `documentation/src/api-v1-users.js`
- `documentation/src/api-v1-users.json`
- `documentation/src/api-v1-users.yml`
Para el archivo `documentation/scaffold.js`
En este ejemplo, se dará prioridad al fichero `api-v1-users.js`, posteriormente al fichero `JSON` o `YAML` según se haya configurado en la variable `HELP_TYPE`.
```js
const ApiGen = require('apidoc-generator')
......@@ -175,7 +154,25 @@ const app = require('../src/app')
ApiGen.scaffold(app)
```
Para el archivo `documentation/server.js`
### Archivo `documentation/generate.js`
Este fichero se encarga de generar la documentación con soporte para ApidocJS y Swagger.
```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))
```
### Archivo `documentation/server.js`
Este fichero, se encarga de ejecutar un servidor para visualizar la documentación.
```js
const ApiGen = require('apidoc-generator')
......@@ -189,3 +186,21 @@ ApiGen.REDIRECT_PATH = `/swagger?url=${SWAGGER_JSON_URL}`
ApiGen.server()
```
### Archivo `package.json`
```json
{
"name": "example",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"start": "node index",
"doc:scaffold": "node documentation/scaffold",
"doc:generate": "node documentation/generate",
"doc:server": "node documentation/server",
"doc:start": "npm run doc:scaffold && npm run doc:generate && npm run doc:server"
}
}
```
-
method: get
path: /api/custom/other/route
-
method: get
path: /api/v1/users/
-
method: get
path: '/api/v1/users/:id'
-
method: post
path: /api/v1/users/
-
method: post
path: /api/v1/users/bulk
-
method: get
path: /ruta/sin/grupo
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment