swagger express next

Always open to ideas.
Positive or negative, all are welcome.
Feel free to contribute an issue or pr.

Описание

Модуль реализует использование пакета swagger-ui в виде промежуточного программного обеспечения express. Простое решение с неограниченными возможностями модификации загрузочной страницы и поддержкой всех настроек скрипта инициализации. Совместим с swagger-ui-express.
Может использоваться без express.

Использование

Прямое

const swagger = require('swagger-express-next').swagger
const express = require('express')
const app = express()
const swaggerDocument = '{"openapi": "3.0.0","info": {"title": "test","version": "1.0"}}'

app.use('/api', swagger({spec: swaggerDocument}, {head: '<title>Swagger Test</title>'}))

app.listen(3000)

В качестве замены для swagger-ui-express

+ require('swagger-express-next').moduleReplace()
const express = require('express')
const app = express()
const swaggerUi = require('swagger-ui-express')
const swaggerDocument = '{"openapi": "3.0.0","info": {"title": "test","version": "1.0"}}'

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

app.listen(3000)

Без express

const {createServer} = require('node:http')
const {swagger} = require('swagger-express-next')
const swaggerDocument = {openapi: "3.0.0", info: {title: "test", version: 1.0}}

createServer((req, res) => {

  swagger({spec: swaggerDocument}, {head: '<title>Swagger Test</title>'})(req, res)

}).listen(3000, '127.0.0.1', e => {
  e ? console.log('HTTP server start error', e) : console.log('HTTP server running ...')
})

Больше примеров смотрите в тестах.

Установка

npm i swagger-express-next

Параметры

Общий пример

const swagger = require('swagger-express-next').swagger
const express = require('express')
const app = express()

const settings = {
  html: {head: '<title>Swagger Test</title>'},
  script: {
    layout:'StandaloneLayout',
    url: 'https://petstore.swagger.io/v2/swagger.json',
  },
  params: {
    script: {default: true, join: true},
    html:   {default: true},
    queryConfig: false,
    type:   {newParam1: {type: 'array', itemsType: 'string'}, newParam2: 'boolean'},
  }
}

app.use('/api', swagger(settings))
// OR
// app.use('/api', swagger(settings.script, settings.html, settings.params))

app.listen(3000)

swagger(script, html, params)

script: object
Смотрите swagger-ui configuration
Исключения:
syntaxHighlight: только object
initOAuth: только object
requestSnippets.languages: array[string]

Типы значений могут отличаться от указанных в документации, так array можно передать в виде строки, если добавляется одно значение, bool в виде строки и т.д. Если скрипт не сможет привести переданные значения к установленным типам будет выдано исключение. Объекты и json преобразуются с помощью JSON.stringify и JSON.parse соответственно, в случаи ошибки исключения не выдаются, описание ошибки можно найти в браузере в виде объекта {objson_error: e} на том ключе которому был передан объект или json.

html: object

• head: string or array or object(values) html теги, добавляются перед </head>
• body: string or array or object(values) html теги, добавляются перед </body>

params: object

• script: object по умолчанию {default: true, join: true}
  • default: boolean
    Использовать параметры предложенные разработчиками swagger-ui при генерации скрипта, будут дополнены / изменены значениями из параметра script.
  • join: boolean
    • true параметры типа массив дополняются пользовательскими значениями.
    • false заменяет массив значений предложенных разработчиками на пользовательский.
• html: object по умолчанию {default: true}
  • default: boolean
    Использовать параметры предложенные разработчиками swagger-ui при генерации страницы загрузки, будут дополнены / изменены значениями из параметра html.
• queryConfig: boolean
  Разрешает передачу параметров в адресной строке.
• type: object or string
  Позволяет передать пользовательские типы для ключей скрипта инициализации.
  Типы могут быть объявлены через объект или строку и соответствовать используемым в стандартных типах.

Совместимость

Тестирование произведено на:
NestJS 8.4.7
Примеры из тестов swagger-ui-express

Для подмены пакета swagger-ui-express используется функция moduleReplace.
Функцию нужно вызвать до импорта swagger-ui-express.

require('swagger-express-next').moduleReplace()
const swaggerUi = require('swagger-ui-express')

Если пакет swagger-ui-express обнаружен в node_modules его директория будет переименована в swagger-ui-express_original. В новую директорию swagger-ui-express копируются файлы из swagger-express-next.