Skip to content

angrocode/swagger-express-next

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

69 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

swagger express next

ver badge down badge

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.

About

new gasket between swagger and express

Resources

License

Stars

Watchers

Forks