Documentación de la API del tutorial de Swagger UI y uso de Node

En el desarrollo de equipos, un buen documento API puede reducir muchos costos de comunicación y también puede permitir que un recién llegado comience rápidamente con el negocio.

prefacio

• Swagger ui es una poderosa herramienta para la generación y prueba de documentos API en línea, y actualmente se considera la mejor.
• ¿Por qué es fácil de usar? Portal de demostración
  • API de soporte para generar automáticamente documentos en línea sincronizados
    • Estos documentos se pueden utilizar para la auditoría API interna del proyecto.
    • Facilite a los evaluadores la comprensión de la API
  • Estos documentos se pueden publicar como parte de la documentación del producto del cliente.
    • Admite la generación de código de especificación API, el código esqueleto del cliente y del servidor generado puede acelerar el desarrollo y las pruebas.

En una palabra, es fácil de usar y potente. A continuación, resumiré cómo crear rápidamente una herramienta de documentación API basada en la interfaz de usuario de Node y Swagger localmente.

Construcción del entorno

• Descargue Swagger UI (también puede descargar el archivo zip directamente)

git clone https://github.com/swagger-api/swagger-ui.git

• instalar expreso
• Crea una carpeta vacía node_app

mkdir node_app

• Inicialice el nodo, cree el archivo package.json()

➜  ~ ✗ >cd node_ap
➜  ~/node_app ✗ >npm init
// 下面的看你心情填写
name: (node_app) node_app
version: (1.0.0)
description:
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)

• instalar expreso

➜ ~/node_app git:(master) ✗ >npm install express --save

• Crear index.js

➜  ~/node_app git:(master) ✗ >vim index.js

• Pegue el siguiente código como index.js

var express = require('express');
var app = express();
app.get('/', function (req, res) {
  res.send('Hello World!');
});

app.listen(3000, function () {
  console.log('Example app listening on port 3000!');
});

• Crea un directorio público vacío en node_app

➜  ~/node_app git:(master) ✗ >mkdir public
➜  ~/node_app git:(master) ✗ >cd public

• modificar ruta

➜  ~/node_app/public git:(master) ✗ >vim ../index.js
//在文件第三行插入下面这句话
app.use('/static', express.static('public'));

• Copie todos los archivos en el directorio dist en el archivo Swagger UI descargado a la carpeta pública.

   
  Estructura de directorios
• nodo abierto

➜  ~/node_app git:(master) ✗ >node index.js

• Abra el navegador e ingrese http://localhost:3000/static/index.html

Hasta ahora, has configurado la demostración oficial localmente. Por supuesto, también puedes crear esto en el servidor.

Escribir documentación y publicar.

• Escribir documentación API usando Swagger Editor
  • La sintaxis del Swagger Editor se basa en yaml, pero no tengas miedo, solo mira la demostración oficial durante 10 minutos.

• exportar prueba.json

   
  Método de exportación
• Coloque test.json en el directorio node_app/public.
• Utilice el editor para url = "http://petstore.swagger.io/v2/swagger.json";modificarurl = "/static/test.json";
• http://localhost:3000/static/index.htmlReinicie el servicio de nodo, abra el documento API que usted mismo escribió en el navegador