swagger Tutorial
Empezando con swagger
Buscar..
Observaciones
Esta sección proporciona una descripción general de qué es Swagger y por qué un desarrollador puede querer usarlo.
También debe mencionar los temas grandes dentro de swagger y vincular a los temas relacionados. Dado que la Documentación para swagger es nueva, es posible que deba crear versiones iniciales de esos temas relacionados.
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 de códigos y editores. La mejor parte de Swagger es que la documentación de los métodos, los parámetros y los modelos están estrechamente integrados en el código del servidor, lo que permite que las API se mantengan siempre sincronizadas. Aquí hay un enlace que ofrece una breve descripción de lo que es swagger: empezar.
Especificaciones de escritura:
Las especificaciones se pueden escribir en JSON o YAML. Y así hacemos 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 swagger:
- Primer enfoque de API (enfoque de arriba a abajo): use el editor swagger → escriba las definiciones swagger → use swagger-codegen y swagger-ui para generar API
- Primer enfoque del servicio (enfoque ascendente): Desarrolle clases de recursos JAX-RS usando anotaciones de swagger → Use swagger-core para generar automáticamente las definiciones de swagger → Usar swagger-codegen y swagger-ui para generar API y documentación de clientes. Lo anterior se puede hacer durante la compilación maven durante el plugin maven swagger.
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. Para instalar Swagger utilizando el administrador de paquetes de Node, ejecute el siguiente comando:
npm install -g swagger
El uso de la bandera '-g' asegurará que el módulo se instale globalmente. A continuación, crearemos un proyecto usando el siguiente comando:
swagger project create <project-name>
Esto le pedirá al usuario que seleccione un marco para desarrollar las API REST. Expreso 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 /
- controladores /
- ayudantes /
- simulacros /
- pavonearse/
- config /
- prueba/
- api /
- controladores /
- ayudantes
- api /
- app.js
- paquete.json
El servidor está básicamente listo ahora y se puede iniciar usando este comando para ejecutarse en la raíz del proyecto:
swagger project start
Si el servidor host está configurado como localhost
y el número de puerto no se modifica en el archivo app.js
, el servidor se inicia en: http://localhost:10010
Ahora se puede usar la interfaz de usuario Swagger para desarrollar aún más nuestras API REST. Esto se puede iniciar en un nuevo terminal usando:
swagger project edit
Esto abrirá el editor de Swagger en una pestaña del navegador en un puerto generado aleatoriamente. En el archivo swagger.yaml se puede ver una solicitud de ejemplo GET de saludo. Cualquier cambio adicional en 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 muestra, hello_world.js debe estar presente en el directorio de los controladores. Además, el valor para el parámetro operationId
representa el nombre de la función en el archivo javascript anterior. Aquí es donde se debe escribir la lógica de negocios. Por lo tanto, nuestra configuración de Swagger está completa y puede utilizarse para desarrollar aún más nuestra API.