Comenzando con la arrogancia

Introducción - Instalación - Configuración (Desarrollo en Node.js)

Introducción:

Swagger es un conjunto de reglas/especificaciones para un formato que describe las API REST. Proporciona un ecosistema de herramientas potente y activamente desarrollado en torno a esta especificación formal, como generadores y editores de código. La mejor parte de Swagger es que la documentación de métodos, parámetros y modelos está estrechamente integrada en el código del servidor, lo que permite que las API permanezcan siempre sincronizadas. Aquí hay un enlace que ofrece una breve descripción general de lo que es swagger: cómo empezar.

Especificaciones de escritura:

Las especificaciones se pueden escribir en JSON o YAML. Y creamos el archivo swagger.json o swagger.yaml en consecuencia. El editor en línea se puede utilizar para crear el archivo. Aquí hay un enlace que describe la sintaxis de las especificaciones: http://swagger.io/specification/

Formas de usar la arrogancia:

  1. Primero enfoque de API (enfoque de arriba hacia abajo): Usar el editor de swagger → Escribir definiciones de swagger → Usar swagger-codegen y swagger-ui para generar API
  2. Primer enfoque de servicio (enfoque de abajo hacia arriba): Desarrollar clases de recursos JAX-RS usando anotaciones swagger → Usar swagger-core para generar automáticamente las definiciones swagger → Usar swagger-codegen y swagger-ui para generar API y documentaciones de clientes. Lo anterior se puede hacer durante la compilación maven durante el complemento swagger maven.

Instalación y configuración

En esta sección, instalaremos swagger, configuraremos la interfaz de usuario de swagger y generaremos el lado del servidor y el SDK del cliente usándolo. Para instalar swagger usando el administrador de paquetes de Node, ejecute el siguiente comando:

npm install -g fanfarronería

El uso del indicador ‘-g’ garantizará que el módulo se instale globalmente. A continuación, crearemos un proyecto usando el siguiente comando:

proyecto swagger crear <nombre-proyecto>

Esto le pedirá al usuario que seleccione un marco para desarrollar las API REST. Express se puede seleccionar para el mismo. Esto creará el directorio del proyecto con los siguientes elementos y un archivo README.md en cada uno de ellos:

-api/ - controllers/ - helpers/ - mocks/ - swagger/

  • configuración/
  • prueba/
    • api/
      • controllers/
      • helpers
  • aplicación.js
  • paquete.json

El servidor está básicamente listo ahora y se puede iniciar usando este comando para ejecutarlo en la raíz del proyecto:

inicio del proyecto swagger

Si el servidor host se configura como localhost y el número de puerto no se modifica en el archivo app.js, entonces el servidor se inicia en: http://localhost:10010. Ahora la interfaz de usuario de Swagger se puede usar para seguir desarrollando nuestras API REST. Esto se puede iniciar en una nueva terminal usando:

edición del proyecto swagger

Esto abrirá el editor de swagger en una pestaña del navegador en un puerto generado aleatoriamente. Ya se puede ver una solicitud hello GET de muestra en el archivo swagger.yaml. Cualquier cambio adicional a este archivo hará que el servidor se reinicie por sí solo.

En la sección de rutas, el valor utilizado para x-swagger-router-controller debe ser el nombre del archivo javascript en la carpeta de controladores. Como ejemplo, hello_world.js debería estar presente en el directorio de controladores. Además, el valor del parámetro operationId representa el nombre de la función en el archivo javascript anterior. Aquí es donde se debe escribir la lógica empresarial. Por lo tanto, nuestra configuración de swagger está completa y se puede utilizar para desarrollar aún más nuestra API.