swagger ui express
5.0.1
| 语句 | 分支 | 功能 | 线 |
|---|---|---|---|
该模块允许您根据swagger.json文件提供自动生成的Swagger-UI生成的API文档。结果是通过路由从API服务器托管的API的Live文档。
Swagger版本是从NPM模块Swagger-UI-Dist取出的。请使用锁定文件或指定要确保在环境中保持一致的Swagger-UI端端版本。
您可能也对：
使用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 ) ) ;或者如果您正在使用Express Router
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 ) ) ;打开http：// <app_host> ： <app_port> /api-docs在浏览器中查看文档。
如果您想根据Swagger Document Checkout Swagger-express-Router设置路由
如果您使用的是Swagger-JSDOC，只需将SwaggerSpec传递到设置功能：
// Initialize swagger-jsdoc -> returns validated swagger spec in json format
const swaggerSpec = swaggerJSDoc ( options ) ;
app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerSpec ) ) ;默认情况下，Swagger Explorer栏是隐藏的，以显示其将选项的“ Explorer”属性传递给设置函数：
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 ) ) ;要将自定义选项（例如validatorUrl）传递给Swaggerui客户端，将对象作为选项的“ Swaggeroptions”属性传递给设置函数：
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 ) ) ;有关所有可用选项，请参阅Swagger UI配置
要自定义Swagger页面的样式，您可以将自定义CSS作为选项的“ CustomCSS”属性传递给设置功能。
例如，隐藏招摇头：
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 ) ) ;您还可以将URL传递到自定义CSS文件，该值必须是文件的公共URL，并且可以是相对或绝对与Swagger路径相对的。
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 ) ) ;您还可以将CSS URL数组传递到加载多个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 ) ) ;如果您想完全控制HTML，则可以提供自己的JavaScript文件，Value接受绝对路径或相对路径。值必须是JS文件的公共URL。
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 ) ) ;您还可以将JS URL数组传递到加载多个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 ) ) ;也可以将内联JavaScript添加为字符串或字符串数组。
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 ) ) ;要从URL加载摇动而不是注入文档，请将null作为第一个参数传递，然后将相对或绝对URL作为“ URL”属性传递给设置功能中的“ Swaggeroptions”。
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 ) ) ;要将来自URL的多个Swagger文档作为资源管理器栏中的下拉文档，请将带有name和url的对象数组传递到设置函数中的“ swaggeroptions”。
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 ) ) ;确保在设置选项中将“ Explorer”选项设置为“ true”，以便可见的下拉选项。
要加载Swagger规格YAML文件，您需要使用能够将YAML转换为JSON的模块；例如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 ) ) ;要根据传入的请求对象在Swagger文件中动态设置主机或任何其他内容，您可以通过REQ对象传递JSON；为了实现这一目标，不要将Swagger JSON传递到设置功能，它将在req对象中寻找swaggerDoc 。
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 ( ) ) ;要运行具有不同的Swagger文档的2个Swagger UI实例，请使用ServeFiles功能而不是服务功能。 ServeFiles功能具有与设置功能相同的签名。
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 ( ) ) ;要渲染指向Swagger文档的链接，以便在Swagger UI中下载 - 然后将Swagger Doc作为端点，并使用URL选项指向它：
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
