swagger ui express
5.0.1
| Заявления | Ветви | Функции | Линии |
|---|---|---|---|
Этот модуль позволяет вам обслуживать сгенерированные API-документы Swagger-UI с автоматическим сгенерированием от Express, основанный на файле swagger.json . Результатом является живая документация для вашего API, размещенного с вашего сервера API по маршруту.
Версия Swagger извлечена из модуля NPM Swagger-Ui-Dist. Пожалуйста, используйте файл блокировки или укажите версию Swagger-Ui-Dist, который вы хотите, чтобы он был согласован в разных средах.
Вы также можете быть заинтересованы в:
Установите, используя 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 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
Чтобы настроить стиль страницы Swagger, вы можете передавать пользовательские CSS в качестве свойства «Customcss» параметров для функции настройки.
Например, чтобы скрыть заголовок Swagger:
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 -адресом файла и может быть относительным или абсолютным для пути чванства.
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 ) ) ;Вы также можете передать массив URL -адресов CSS для загрузки нескольких файлов 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, значение принимает абсолютный или относительный путь. Значение должно быть публичным 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'
} ;
app . use ( '/api-docs' , swaggerUi . serve , swaggerUi . setup ( swaggerDocument , options ) ) ;Вы также можете передать массив URL -адресов JS для загрузки нескольких файлов 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 ) ) ; Чтобы загрузить несколько документов Swagger из URL -адресов в виде раскрывающегося списка в бане Explorer, передайте массив объекта с name и url , чтобы «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 на основе входящего объекта запроса вы можете передать JSON через объект REQ; Чтобы достичь этого, просто не передайте Swagger JSON к функции настройки, и он будет искать swaggerDoc в объекте 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 ( ) ) ;Чтобы запустить 2 экземпляра UI Swagger с различными документами Swagger, используйте функцию FUNCEFILES вместо функции обслуживания. Функция FERFILES имеет такую же подпись, что и функция настройки.
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 для загрузки в UI Swagger - затем подайте DOC Swagger в качестве конечной точки и используйте опцию 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
