swagger ui express

Swagger Ui Express

Declaraciones	Sucursales	Funciones	Pauta

Este módulo le permite servir documentos API generados por Swagger-UI generados por auto-UI de Express, basados ​​en un archivo swagger.json . El resultado es la documentación de vida para su API alojada desde su servidor API a través de una ruta.

La versión Swagger se extrae del módulo NPM Swagger-Ui-Dist. Utilice un archivo de bloqueo o especifique la versión de Swagger-Ui-Dist que desea asegurarse de que sea consistente en todos los entornos.

También puede estar interesado en:

• Swagger-JSDOC: le permite marcar rutas con comentarios de JSDOC. Luego produce una configuración Swagger YML completa dinámicamente, que puede pasar a este módulo para producir documentación. Consulte a continuación en la sección de uso para obtener más información.
• Herramientas de arrogancia: diversas herramientas, incluido el editor de Swagger, Swagger Code Gen, etc.

Uso

Instalar usando NPM:

$ npm install swagger-ui-express

Express Setup app.js

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument ) ) ;

o si está utilizando el enrutador expreso

 const router = require ( 'express' ) . Router ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

router . use ( '/api-docs' , swaggerUi . serve ) ;
router . get ( '/api-docs' , swaggerUi . setup ( swaggerDocument ) ) ;

Abra http: // <app_host> : <app_port> /api-docs en su navegador para ver la documentación.

Si desea configurar el enrutamiento basado en el documento de Swagger, consulte Swagger-Express-Router

swagger-jsdoc

Si está utilizando Swagger-JSDOC, simplemente pase el SwaggersPec a la función de configuración:

 // Initialize swagger-jsdoc -> returns validated swagger spec in json format
const swaggerSpec = swaggerJSDoc ( options ) ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerSpec ) ) ;

Explorador de arrogancia

De forma predeterminada, la barra de explorador Swagger está oculta, para mostrar que pasa verdadera como la propiedad 'Explorer' de las opciones a la función de configuración:

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  explorer : true
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

Opciones de arrogancia personalizadas

Para pasar opciones personalizadas, por ejemplo, ValidatorUrl, al cliente Swaggerui, pase un objeto como la propiedad de 'swaggeroptions' de las opciones a la función de configuración:

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  swaggerOptions : {
    validatorUrl : null
  }
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

Para todas las opciones disponibles, consulte la configuración de la interfaz de usuario de Swagger

Estilos CSS personalizados

Para personalizar el estilo de la página Swagger, puede pasar CSS personalizado como la propiedad 'CustomCSS' de las opciones a la función de configuración.

Por ejemplo, para esconder el encabezado de arrogancia:

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customCss : '.swagger-ui .topbar { display: none }'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

Estilos CSS personalizados de URL

También puede pasar la URL a un archivo CSS personalizado, el valor debe ser la URL pública del archivo y puede ser relativo o absoluto para la ruta de arrogancia.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customCssUrl : '/custom.css'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

También puede pasar una variedad de URL CSS para cargar múltiples archivos CSS.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customCssUrl : [
    '/custom.css' ,
    'https://example.com/other-custom.css'
  ]
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

JS personalizado

Si desea tener control total sobre su HTML, puede proporcionar su propio archivo JavaScript, el valor acepta una ruta absoluta o relativa. El valor debe ser la URL pública del archivo JS.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJs : '/custom.js'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

También puede pasar una matriz de URL JS para cargar varios archivos JS.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJs : [
    '/custom.js' ,
    'https://example.com/other-custom.js'
  ]
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

También es posible agregar JavaScript en línea, ya sea como cadena o matriz de cadena.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJsStr : 'console.log("Hello World")'
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ; 

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
  customJsStr : [
    'console.log("Hello World")' ,
    `
    var x = 1
    console.log(x)
    `
  ]
} ;

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;

Cargar arrogancia desde la URL

Para cargar su arrogancia de una URL en lugar de inyectar el documento, pase null como el primer parámetro y pase la URL relativa o absoluta como la propiedad 'URL' a 'Swaggeroptions' en la función de configuración.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;

var options = {
  swaggerOptions : {
    url : 'http://petstore.swagger.io/v2/swagger.json'
  }
}

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( null , options ) ) ;

Para cargar múltiples documentos de arrogancia de las URL como un menú desplegable en la barra del explorador, pase una matriz de objeto con name y url a la propiedad 'URL' a 'Swaggeroptions' en la función de configuración.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;

var options = {
  explorer : true ,
  swaggerOptions : {
    urls : [
      {
        url : 'http://petstore.swagger.io/v2/swagger.json' ,
        name : 'Spec1'
      } ,
      {
        url : 'http://petstore.swagger.io/v2/swagger.json' ,
        name : 'Spec2'
      }
    ]
  }
}

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( null , options ) ) ;

Asegúrese de que la opción 'Explorer' esté configurada en 'Verdadero' en sus opciones de configuración para que el menú desplegable sea visible.

Cargar arrogancia desde el archivo yaml

Para cargar su archivo Swagger Specification Yaml, debe usar un módulo capaz de convertir Yaml a JSON; Por ejemplo yaml .

 npm install yaml

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const fs = require ( "fs" )
const YAML = require ( 'yaml' )

const file  = fs . readFileSync ( './swagger.yaml' , 'utf8' )
const swaggerDocument = YAML . parse ( file )

app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument ) ) ;

Modificar el archivo Swagger en la marcha antes de la carga

Para establecer dinámicamente el host, o cualquier otro contenido, en el archivo Swagger basado en el objeto de solicitud entrante, puede pasar el JSON a través del objeto REQ; Para lograr esto, no pase el Swagger JSON a la función de configuración y buscará swaggerDoc en el objeto req .

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = { }

app . use ( '/api-docs' , function ( req , res , next ) {
    swaggerDocument . host = req . get ( 'host' ) ;
    req . swaggerDoc = swaggerDocument ;
    next ( ) ;
} , swaggerUi . serveFiles ( swaggerDocument , options ) , swaggerUi . setup ( ) ) ;

Dos documentos de arrogancia

Para ejecutar 2 instancias de UI de Swagger con diferentes documentos de arrogancia, use la función ServFiles en lugar de la función de servicio. La función ServFiles tiene la misma firma que la función de configuración.

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocumentOne = require ( './swagger-one.json' ) ;
const swaggerDocumentTwo = require ( './swagger-two.json' ) ;

var options = { }

app . use ( '/api-docs-one' , swaggerUi . serveFiles ( swaggerDocumentOne , options ) , swaggerUi . setup ( swaggerDocumentOne ) ) ;

app . use ( '/api-docs-two' , swaggerUi . serveFiles ( swaggerDocumentTwo , options ) , swaggerUi . setup ( swaggerDocumentTwo ) ) ;

app . use ( '/api-docs-dynamic' , function ( req , res , next ) {
  req . swaggerDoc = swaggerDocument ;
  next ( ) ;
} , swaggerUi . serveFiles ( ) , swaggerUi . setup ( ) ) ;

Enlace al documento Swagger

Para representar un enlace al documento Swagger para descargar dentro de la interfaz de usuario de Swagger, luego sirva al Doc de Swagger como un punto final y use la opción URL para señalarlo:

 const express = require ( 'express' ) ;
const app = express ( ) ;
const swaggerUi = require ( 'swagger-ui-express' ) ;
const swaggerDocument = require ( './swagger.json' ) ;

var options = {
    swaggerOptions : {
        url : "/api-docs/swagger.json" ,
    } ,
}
app . get ( "/api-docs/swagger.json" , ( req , res ) => res . json ( swaggerDocument ) ) ;
app . use ( '/api-docs' , swaggerUi . serveFiles ( null , options ) , swaggerUi . setup ( null , options ) ) ; 

Requisitos

• Nodo v0.10.32 o superior
• Expresar 4 o más

Pruebas

• Instalar Phantom
• npm install
• npm test