https://github.com/funny-bytes/openapi2html
https://github.com/funny-bytes/openapi2html
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/funny-bytes/openapi2html
- Owner: funny-bytes
- Created: 2018-02-04T18:43:49.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2025-01-16T13:53:56.000Z (over 1 year ago)
- Last Synced: 2025-08-09T12:45:53.619Z (10 months ago)
- Language: JavaScript
- Size: 1.31 MB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
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.
[](https://coveralls.io/github/funny-bytes/openapi2html?branch=master)
[](https://david-dm.org/funny-bytes/openapi2html)
[](https://codeclimate.com/github/funny-bytes/openapi2html/maintainability)
[]()
[](https://github.com/airbnb/javascript)
[]()
## Install
```bash
npm install openapi2html
```
## Usage
First, use `swagger-parser` to parse your api from `json` or `yaml`. Then, use `openapi2html` to generate html, e.g.:
```js
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.:
```js
...
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 colors `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark`. Please do not use `danger` because this is already used for `deprecated`. The default theme color is `secondary`. 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` (default `true`), `host` (default `true`), `basePath` (default `true`), `contact` (default `false`), `license` (default `false`), `termsOfService` (default `false`), `schemes` (default `true`), `consumes` (default `true`), `produces` (default `true`)
## Styling
The generated html doesn't provide any styling. It is plain Bootstrap 4 compatible html, i.e.,
it uses `
` through ``, ``, ``, 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
...
.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;
}
```