Apidoc Creator
La forma tradicional de documentar servicios web RESTFUL, es escribir la descripción de la ruta en forma de comentario en el caso de ApidocJS o en un fichero con formato JSON en el caso de Swagger.
ApidocJS es muy flexible al momento de describir la ruta de un servicio, sin embargo, describir las rutas en forma de comentarios no es la adecuada si se quiere automatizar este proceso.
Apidoc Creator utiliza ApidocJS para crear la documentación y ofrece un sistema diferente para describir las rutas, fácil de implementar. Para describir los datos de entrada y salida, utiliza la librería Field Creator.
Características
- Devuelve la descripción de una ruta en formato de texto plano, según el formato que establece ApidocJS.
- Devuelve la descripción de un modelo Sequelize en formato MD (MarkDown).
Propiedades soportadas:
Propiedad | Descripción |
---|---|
name |
Nombre asignado a la ruta. |
method |
Método HTTP para acceder al recurso. |
path |
Ruta del recurso (URI). |
group |
Grupo al que pertenece la ruta. |
version |
Versión de la ruta. |
description |
Descripción de la ruta. |
input |
Datos de entrada. Objeto de tipo FieldGroup. |
output |
Datos de salida. Objeto de tipo FieldGroup. |
inputExamples |
Ejemplos de datos de entrada. |
outputExamples |
Ejemplos de datos de salida. |
permissions |
Lista de todos los roles que pueden acceder al recurso. |
sampleRequest |
Dirección URL de la ruta para probar una petición. |
input
y output
Propiedades const INPUT = headers : FIELD params : FIELD query : FIELD body : FIELD const OUTPUT = FIELD // Siempre sera body
Para crear los objetos input
y output
, se recomienda utilizar la librería field-creator.
onCreate
Función Esta función puede utilizarse para realizar una tarea de forma automática cada vez que se defina una ruta.
{ console // TODO} const router = Apidoc routerrouterrouterrouterrouter
Instalación
Para instalar sobre un proyecto, ejecutar el siguiente comando:
$ npm install --save apidoc-creator
Ejemplo 1. Descripción de modelos
const Apidoc =const Field =LIBRO = sequelizeconst markdown = Apidocconsole/*### **libro**Representa a una obra literaria.| Atributo | Tipo de dato | Descripción ||--------------------|----------------------------------------|--------------------------------|| `id` [ PK ] | `Integer` | ID del libro. || `titulo` | `String` | Título del libro. || `precio` | `Float` | Precio del libro. [Bs] || `estado` | `Enum=ACTIVO,INACTIVO` | Estado del registro. |*/
Ejemplo 2. Descripción de rutas.
const Apidoc =const Field THIS =const express =const app ={approutemethodroutepath routecontrollerconsole/*** @api* @apiName crearLibro* @apiGroup Libro* @apiDescription Crea un libro.* @apiVersion 1.0.0* @apiParam (Datos de entrada - body)* @apiParam (Datos de entrada - body)* @apiParam (Datos de entrada - body)* @apiParamExample* {* "titulo": "El gato negro",* "precio": 12.99,* "estado": "ACTIVO"* }* @apiSuccess (Respuesta - body)* @apiSuccess (Respuesta - body)* @apiSuccess (Respuesta - body)* @apiSuccess (Respuesta - body)* @apiSuccessExample* HTTP/1.1 200 Ok* {* "id": 1,* "titulo": "El gato negro",* "precio": 12.99,* "estado": "ACTIVO"* }*/}const router = Apidocrouter