bos-openapi-doc-server
v1.0.0
Published
BlueOak Server Middleware to serve OpenAPI (Swagger) docs
Downloads
3
Maintainers
Readme
BlueOak Server Middleware to serve OpenAPI (Swagger) docs
Using BlueOak Server, started with nodemon
, and this project, you can author OpenAPI (swagger)
specs using your editor, and have them rendered and served to your browser in ReDoc.
This BlueOak Server middleware uses ReDoc to serve the OpenAPI (Swagger) specs defined in a BlueOak Server project (template).
installation
In a BlueOak Server project (template):
$ npm i --save bos-openapi-doc-server
configuration
Since this is BlueOak Server middleware, it won't be used unless you configure it to be used.
In your server config (e.g. config/default.json
):
- add
"bos-openapi-doc-server"
to your list of"middleware"
- customize what and where the docs get served in the
swagger.docPublish
object
list of config options affecting this functionality
swagger.docPublish.context
(optional): where the ReDoc-rendered specs should be served from- default:
"/docs"
- default:
swagger.docPublish.redocUrl
(optional): provides the ability to override where to get ReDoc from- default: the URL for the v1.x.x published
redoc.min.js
from GitHub - you can also use a file path if you want to use a local copy
- default: the URL for the v1.x.x published
swagger.docPublish.templatePath
(optional): facilitates using your own custom ReDoc template- the template may use whiskers syntax to have the follow variables added:
title
: the title for the spec given in the OpenAPI definitionversion
: the version of the spec given in the OpenAPI definitionspecObject
: a JavaScript Object representing the specificationspecUrl
: the URL where BOS is serving the JSON representation of the OpenAPI definitionredocSrc
: the location of the source file for ReDoc, if it is available locallyredocUrl
: the location of the ReDoc source if it is to be retrieved over the networkredocOptions
: a JavaScript Object into which theswagger.docPublish.redocOptions
object will be passed
- the default template at
templates/openapi-doc.html
is a good starting point for customization
- the template may use whiskers syntax to have the follow variables added:
swagger.docPublish.redocOptions
(optional): an object with any customizations to ReDocs behavior following the descriptions of the<redoc>
tag attributes in camelCase
sample default.json
config
{
"express": {
"port": "3003",
"middleware": [
"bos-openapi-doc-server",
"bodyParser"
]
},
"cluster": {
"maxWorkers": 1
},
"bodyParser": {
"json": {}
},
"swagger": {
"serve": true,
"useLocalhost": true,
"refCompiler": {
"api-v1": {
"baseSpecFile": "api-v1.yaml",
"refDirs": [
"v1"
]
}
},
"docPublish": {
"context": "/docs",
"templatePath": "lib/templates/my-spec-docs.html",
"redocOptions": {
"scrollYOffset": 50,
"suppressWarnings": true,
"lazyRendering": true,
"requiredPropsFirst": true
}
}
}
}
That config will cause the spec defined in swagger/api-v1.yaml
to be served at
localhost:3003/docs/${api-path}
, using the custom ReDoc template in your project
at lib/templates/my-spec-docs.html
.