hapi-swagger-static
Advanced tools
A small companion plugin for `hapi-swagger` or `hapi-swaggered` providing a static html documentation page as hapi route
Plugin for Hapi providing a static html documentation page.
It's a small companion plugin for hapi-swagger or hapi-swaggered
to create a static page from the /swagger.json endpoint.
The static page is provided as route /documentation.html (can be renamed).
It supports most of Swagger 2.0 / Open API 2.0.
Tested with
npm install hapi-swagger-static
Register the plugin with Hapi server like this:
const Hapi = require('@hapi/hapi');
const HapiSwagger = require('hapi-swagger');
const HapiSwaggerStatic = require('hapi-swagger-static');
const Inert = require('@hapi/inert');
const Vision = require('@hapi/vision');
const server = new Hapi.Server({
port: 3000,
});
const provision = async () => {
await server.register({ plugin: Inert });
await server.register({ plugin: Vision });
// first, add your api routes to hapi
await server.register({ // second, register `hapi-swagger` plugin
plugin: HapiSwagger,
options: { ... },
});
await server.register({ // last, register this plugin
plugin: HapiSwaggerStatic,
options: { ... },
});
await server.start();
};
provision();
The plugin provides the following options:
| Option | Default | Description |
|---|---|---|
path | /documentation.html | The endpoint providing the static documentation page. |
swaggerEndpoint | /swagger.json | The endpoint to read the Swagger API specification from. |
cache | { privacy: 'public', expiresIn: 60 * 60 * 1000 } // one hour | Hapi's route.options.cache to be assigned to the static documentation endpoint. Please refer to the Hapi docs for more information. |
auth | - | Hapi's route.options.auth to be assigned to the static documentation endpoint. Please refer to the Hapi docs for more information. By default, this option is not set, i.e., inheriting auth settings from Hapi's server.options.routes.auth. |
headers | {} | The request's authorization header is automatically forwarded to the /swagger.json endpoint. If you need any additional headers, add them through the headers option. |
template | - | This plugin prefers vision to render the api into a page. template is the template filename and path, relative to the templates path configured via the server views manager. The api data is provided as view context. Assuming Handlebars or Mustache as your template engine, e.g., you can use {{api.info.title}} in the template to get hold of the api title. Use {{{api.html}}} (with three curly brackets here!) in the template for rendering the api's html content. |
viewOptions | {} | The options passed to the view via h.view(). If your default layout does not provide the Bootstrap 4 CSS resources (Bootstrap's JS is not needed), you should provide a special layout for your template. See the example below. |
o2hOptions | {} | The options passed to openapi2html. Please refer to openapi2html for more information. |
This example assumes Handlebars or Mustache as template engine. It sets the following plugin options:
{ template: 'api', // referring to the view file `api.html` below
viewOptions: {
layout: 'api-layout' // referring to the layout file `api-layout.html` below
}
}
View example, e.g., api.html to be placed into your view location:
{{{api.html}}}
Layout example, e.g., api-layout.html to be placed into your layout location:
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<link href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css" rel="stylesheet">
<link href='/public/api.css' rel='stylesheet' type='text/css' />
<title>{{api.info.title}}</title>
</head>
<body>
<div class="container">
{{{content}}}
<footer>Your company; for internal use only</footer>
</div>
</body>
</html>
Style example, e.g., api.css to be placed into /public, containing some minor adjustments to Bootstrap 4:
.h2, h2 {
margin-top: 1rem;
}
.h4, h4 {
margin-top: .5rem;
}
.card {
margin-bottom: 1rem;
}
.o2h-description p {
color: grey;
margin-bottom: .5rem;
}
.card .card-body .h4, .card .card-body h4 {
border-top: 1px solid #eee;
margin-top: 1rem;
padding-top: 1rem;
}
.card .card-body .h5, .card .card-body h5 {
margin-top: 1rem;
}
.card .card-body .o2h-description p {
margin-bottom: 0;
}
.card .card-body .o2h-example pre {
background-color: #eee;
font-size: small;
}
.o2h-parameter h5 .badge {
font-size: small;
}
FAQs
A small companion plugin for `hapi-swagger` or `hapi-swaggered` providing a static html documentation page as hapi route
The npm package hapi-swagger-static receives a total of 175 weekly downloads. As such, hapi-swagger-static popularity was classified as not popular.
We found that hapi-swagger-static demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.