swagger ui express
5.0.1
| Declarações | Galhos | Funções | Linhas |
|---|---|---|---|
Este módulo permite que você sirva documentos de API gerados por swagger-ui gerados automaticamente do Express, com base em um arquivo swagger.json . O resultado é a documentação viva da sua API hospedada no seu servidor de API por meio de uma rota.
A versão Swagger é retirada do módulo NPM Swagger-ui-Dist. Use um arquivo de bloqueio ou especifique a versão do swagger-ui-dist que você deseja garantir que ele seja consistente entre os ambientes.
Você também pode estar interessado em:
Instale usando o 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 ) ) ;ou se você estiver usando o roteador expresso
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 no seu navegador para visualizar a documentação.
Se você deseja configurar o roteamento com base no documento Swagger Checkout Swagger-Express-Router
Se você estiver usando o swagger-jsdoc, simplesmente passe o swaggerspec para a função de configuração:
// Initialize swagger-jsdoc -> returns validated swagger spec in json format
const swaggerSpec = swaggerJSDoc ( options ) ;
app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerSpec ) ) ;Por padrão, a barra do Swagger Explorer está escondida, para exibi -la, passando como a propriedade 'Explorer' das opções para a função de configuração:
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 ) ) ;Para passar as opções personalizadas, por exemplo, validatorurl, para o cliente Swaggerui, passe um objeto como a propriedade 'Swaggerroptions' das opções para a função de configuração:
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 as opções disponíveis, consulte a configuração da interface do usuário do Swagger
Para personalizar o estilo da página Swagger, você pode passar o CSS personalizado como a propriedade 'CustomCSS' das opções para a função de configuração.
Por exemplo, para esconder o cabeçalho da arrogância:
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 ) ) ;Você também pode passar o URL para um arquivo CSS personalizado, o valor deve ser o URL público do arquivo e pode ser relativo ou absoluto ao caminho da arrogância.
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 ) ) ;Você também pode passar uma matriz de URLs CSS para carregar vários arquivos 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 ) ) ;Se você deseja ter controle total sobre o seu HTML, pode fornecer seu próprio arquivo JavaScript, o Value aceita caminho absoluto ou relativo. O valor deve ser o URL público do arquivo 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 ) ) ;Você também pode passar uma matriz de URLs JS para carregar vários arquivos 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 ) ) ;Também é possível adicionar javascript embutido, como string ou matriz de string.
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 ) ) ; Para carregar sua arrogância a partir de um URL em vez de injetar o documento, passe null como o primeiro parâmetro e passe o URL relativo ou absoluto como a propriedade 'URL' para 'swaggeroptions' na função de configuração.
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 carregar vários documentos de swagger dos URLs como um menu suspenso na barra do Explorer, passe uma matriz de objeto com name e url para a propriedade 'URLs' para 'swaggeroptions' na função de configuração.
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 ) ) ;Verifique se a opção 'Explorer' está definida como 'True' em suas opções de configuração para que o suspensão seja visível.
Para carregar o arquivo YAML da especificação Swagger, você precisa usar um módulo capaz de converter YAML em JSON; Por exemplo, 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 ) ) ; Para definir dinamicamente o host, ou qualquer outro conteúdo, no arquivo Swagger com base no objeto de solicitação de entrada, você pode passar o JSON através do objeto REQ; Para conseguir isso, simplesmente não passa o Swagger JSON para a função de configuração e ele procurará swaggerDoc no 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 ( ) ) ;Para executar duas instâncias da interface do mar com documentos de swagger diferentes, use a função de arquivos de servir em vez da função de servir. A função Sirtfiles possui a mesma assinatura que a função de configuração.
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 ( ) ) ;Para renderizar um link para o documento Swagger para download dentro da interface do usuário do Swagger - sirva o Doc Swagger como um ponto final e use a opção URL para apontar:
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 ) ) ; npm installnpm test
