Skip to content

Instantly share code, notes, and snippets.

@oseiskar

oseiskar/swagger-yaml-to-html.py

Last active April 23, 2025 11:07
Show Gist options
  • Save oseiskar/dbd51a3727fc96dcf5ed189fca491fb3 to your computer and use it in GitHub Desktop.
Save oseiskar/dbd51a3727fc96dcf5ed189fca491fb3 to your computer and use it in GitHub Desktop.
Download ZIP
Converts Swagger YAML to a static HTML document (needs: pip install PyYAML)
Raw
swagger-yaml-to-html.py
#!/usr/bin/python
#
# Copyright 2017 Otto Seiskari
# Licensed under the Apache License, Version 2.0.
# See http://www.apache.org/licenses/LICENSE-2.0 for the full text.
#
# This file is based on
# https://github.com/swagger-api/swagger-ui/blob/4f1772f6544699bc748299bd65f7ae2112777abc/dist/index.html
# (Copyright 2017 SmartBear Software, Licensed under Apache 2.0)
#
"""
Usage:
python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html
"""
import yaml, json, sys
TEMPLATE = """
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Swagger UI</title>
<link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.24.2/swagger-ui.css" >
<style>
html
{
box-sizing: border-box;
overflow: -moz-scrollbars-vertical;
overflow-y: scroll;
}
*,
*:before,
*:after
{
box-sizing: inherit;
}
body {
margin:0;
background: #fafafa;
}
</style>
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.24.2/swagger-ui-bundle.js"> </script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.24.2/swagger-ui-standalone-preset.js"> </script>
<script>
window.onload = function() {
var spec = %s;
// Build a system
const ui = SwaggerUIBundle({
spec: spec,
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
window.ui = ui
}
</script>
</body>
</html>
"""
spec = yaml.load(sys.stdin, Loader=yaml.FullLoader)
sys.stdout.write(TEMPLATE % json.dumps(spec))
@diego3
Copy link

diego3 commented Sep 10, 2019

Amazing

@vinamraagrawal
Copy link

First of all thank you so much for the script. However, when I am trying to use it, it is working perfectly except it is not able to include (Authorise) in the html. Can you please let me know how this thing could be done?

@imvishalpatel
Copy link

imvishalpatel commented Nov 1, 2019 •
edited
Loading

you need python3 to successfully run this script.

Selection_023

Also, I deleted the search bar by adding

window.ui = ui

var elements = document.getElementsByClassName("download-url-wrapper");
while(elements.length > 0){
    elements[0].parentNode.removeChild(elements[0]);
}

after window.ui = ui

@blimey74
Copy link

blimey74 commented Nov 6, 2019

Thanks a million for this script. Is anyone else getting "Cannot read property '0' of undefined" in Chrome and knows how to remove this error?

@oseiskar
Copy link
Author

you need python3 to successfully run this script.

@vnation: That is not true. I can run this just fine with Python 2.7. However, you do need a rather recent version (5.1+) of PyYAML, for example version 3.2 does not work. Can be fixed with pip install -U PyYAML

@pedr0-fr
Copy link

Have been using this script with no problems, it's awesome. @CZDiego an easier way to remove the top bar is replacing 'StandaloneLayout' by 'BaseLayout'.

Does anyone know of a similar file but that works with Open API 3?

@ranggabimantika
Copy link

its 2020 now, and this awesome work is still works
thank you!!

@nigredo13
Copy link

Hi, really great !!!
But how do I use it with jwt auth (Bearer etc) ?
it is defined in the yaml and with swagger editor works...

@ezeholz
Copy link

ezeholz commented Apr 11, 2020

Hi there, so I was looking out why the auth isn't working. You just have to update the CDN.
Right after <div id="swagger-ui"></div> you should change the two script lines by

<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.24.2/swagger-ui-bundle.js"> </script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.24.2/swagger-ui-standalone-preset.js"> </script>

And that's all, your page will be render with the auth box.

Tagging people who ask for it:
@vinamraagrawal
@nigredo13

@oseiskar
Copy link
Author

@ezeholtz Thanks. I now applied those changes and also updated the CSS.

@ezeholz
Copy link

ezeholz commented Apr 11, 2020

@oseiskar You can also use the io library to force the encoding in UTF-8, it's just a few more lines to be sure that anyone can use it.

import yaml, json, sys, io

input_stream = io.TextIOWrapper(sys.stdin.buffer, encoding='utf-8')

spec = yaml.load(input_stream, Loader=yaml.FullLoader)
sys.stdout.write(TEMPLATE % json.dumps(spec))

@friderikceljski
Copy link

Thanks!! :) No idea why swagger editor doesn't have an option to export as html by default...

@ngohieutp
Copy link

Great! Many thanks.

@AlefCS
Copy link

AlefCS commented Jul 4, 2020

image
I deleted the search bar by adding

window.ui = ui

var elements = document.getElementsByClassName("topbar");
while(elements.length > 0){
    elements[0].parentNode.removeChild(elements[0]);
}

right after the part of window.ui = ui

It could also be done by removing SwaggerUIStandalonePreset and layout: "StandaloneLayout" as mentioned in this comment in SwaggerUI repo.

@ShreyaKarmakar
Copy link

D:\convertyaml>python swagger-yaml-to-html.py < D:\convertyaml\swagger.yaml > do
c.html
Traceback (most recent call last):
File "swagger-yaml-to-html.py", line 8, in
import yaml, json, sys
ImportError: No module named yaml

Getting this error

installing pyyaml works fine.

@kukovecz
Copy link

kukovecz commented Nov 5, 2020

Hey @oseiskar,

This is fine and clean solution, and I really love and use it.
But discovered it lacks one feature, I am really eager to see: I have my OpenAPI YAML file split to a bunch of small yaml reference files, like this structure:

.
├── ami.yaml
├── resources
│   ├── examples
│   │   ├── examle1.yaml
│   │   └── examle2.yaml
│   ├── headers
│   │   └── headers1.yaml
│   ├── parameters
│   │   |── parameter1.yaml
│   │   |── parameter2.yaml
│   │   └── parameter3.yaml
│   └── schemas
│       ├── schema1.yaml
│       └── schema2.yaml
└── swagger-yaml-to-html.py

The main API is defined in the api.yaml, and uses a lot of $ref references for the other yaml files.

What do you think, can this script easily enchanted to handle this?

Thanks in advance!

@oseiskar
Copy link
Author

Hi @kukovecz

What do you think, can this script easily enchanted to handle this?

It's might be possible to extend the script to somehow merge the files, but I'm not aware of a very simple, as in only a few lines of code, quick fix for this. I have mostly been using this scripts with APIs defined in single YAML files, but agree that supporting multiple files would be a great addition. I have no plans to implement it myself though.

@kukovecz
Copy link

Hi @kukovecz

What do you think, can this script easily enchanted to handle this?

It's might be possible to extend the script to somehow merge the files, but I'm not aware of a very simple, as in only a few lines of code, quick fix for this. I have mostly been using this scripts with APIs defined in single YAML files, but agree that supporting multiple files would be a great addition. I have no plans to implement it myself though.

Thanks for the response. Finally I solved my problem, using swagger-ui-watcher as workaround, as it has a --bundle option to create a whole big JSON file from the linked reference files. I was also planning on using it because of this OpenAPI issue.

@juandavidg890121
Copy link

juandavidg890121 commented Nov 23, 2020 •
edited
Loading

I generate the html file well using the command
docker run --rm -i yousan/swagger-yaml-to-html < jobs.yaml > jobs.html
But the script does not generate the Schema in the responses
image
If you use the online editor you get the schemas well
image
How can I obtain that?

@oseiskar
Copy link
Author

@juandavidg890121: You could try updating the Swagger version on these lines:

...and run the original Python script. I'm not sure when @yousan has las updated their Docker version. The older version of Swagger currently used here probably does not support showing the schema

@juandavidg890121
Copy link

@juandavidg890121: You could try updating the Swagger version on these lines:

...and run the original Python script. I'm not sure when @yousan has las updated their Docker version. The older version of Swagger currently used here probably does not support showing the schema

@oseiskar Thanks, it works perfectly

@yousan
Copy link

yousan commented Nov 25, 2020

@juandavidg890121 @oseiskar
Hello.

I fixed from oseiskar's code. (Thank you @oseiskar)

https://github.com/yousan/swagger-yaml-to-html/blob/master/swagger-yaml-to-html.py

Docker Hub have built the new one.

https://hub.docker.com/r/yousan/swagger-yaml-to-html/builds

Please try the latest image if you can ;)

Thank you.

@wgarunap
Copy link

Many Thanks!

@petrimma
Copy link

petrimma commented Jun 1, 2021

Thank you.

@suyashcjoshi
Copy link

nice one and thanks @yousan

@vuonghv
Copy link

vuonghv commented Oct 5, 2021

The elegant solution 💯

@shiwoopark
Copy link

shiwoopark commented Jan 19, 2022 •
edited
Loading

We just can simply use redoc-cli !!!
https://redoc.ly/docs/redoc/quickstart/cli/

@Sachin-Suresh
Copy link

Sachin-Suresh commented Mar 17, 2022 •
edited
Loading

I am unable to get the header examples in the HTML-generated file. However, i can see the example in the Swagger editor. Anyone facing this issue?

@iamFoxx
Copy link

iamFoxx commented Sep 3, 2022

We just can simply use redoc-cli !!! https://redoc.ly/docs/redoc/quickstart/cli/

Thank you.

@williamdevitt7
Copy link

I love you.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment