openapi2html
v1.1.22
Published
Yet another static html generator for Open API 2.0 / Swagger 2.0
Downloads
1,361
Readme
openapi2html
Yet another static html generator for Open API 2.0 / Swagger 2.0. It generates Bootstrap 4 compatible static html from your Swagger API spec. Not all the Swagger features are supported -- if you miss anything, let me know.
Install
npm install openapi2html
Usage
First, use swagger-parser
to parse your api from json
or yaml
. Then, use openapi2html
to generate html, e.g.:
const parser = require('swagger-parser');
const openapi2html = require('openapi2html');
...
const api = await parser.parse('my-api.yaml');
const html = openapi2html(api);
Options
openapi2html
may take a second parameter for options, e.g.:
...
const options = {
tagColors: {
pet: 'primary',
store: 'warning',
user: 'success'
},
show: {
host: false
}
};
const html = openapi2html(api, options);
There are the following options:
tagColors
maps your operations' tags to Bootstrap theme colorsprimary
,secondary
,success
,danger
,warning
,info
,light
,dark
. Please do not usedanger
because this is already used fordeprecated
. The default theme color issecondary
. If you use custom colors, you need to provide the according CSS classes, e.g.,badge-mycolor
. Hex color values are not supported.show
is used for switching on or off certain information. The following is supported:version
(defaulttrue
),host
(defaulttrue
),basePath
(defaulttrue
),contact
(defaultfalse
),license
(defaultfalse
),termsOfService
(defaultfalse
),schemes
(defaulttrue
),consumes
(defaulttrue
),produces
(defaulttrue
)
Styling
The generated html doesn't provide any styling. It is plain Bootstrap 4 compatible html, i.e.,
it uses <h1>
through <h6>
, <code>
, <a>
, as well as Bootstrap's Card and Badge components.
In addition, there are classes o2h-*
attached such as
o2h-operation-get
to allow some customized styling.
This is what worked for me:
<html>
<head>
...
<link href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css" rel="stylesheet">
<style>
.card {
margin-bottom: 1rem;
}
.h2, h2 {
margin-top: 1rem;
}
.h4, h4 {
margin-top: .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;
}
.o2h-description p {
color: grey;
margin-bottom: .5rem;
}
.card .card-body .o2h-description p {
margin-bottom: 0;
}
.card .card-body .o2h-example pre {
background-color: #eee;
}
.o2h-parameter h5 .badge {
font-size: small;
}
</style>
</head>
<body>
<div class="container">
<!-- include api html here -->
</div>
</body>
</html>