Menu
So I'm trying to make a navigation panel sidebar on the swagger-ui front page. I'm using the http://startbootstrap.com/template-overviews/simple-sidebar/ simple sidebar. I tried putting that code ( + the css file) in the dist folder of swagger-ui and then, in my dist/index.html, I tried to add it but it's not displaying properly. I think this is because swagger content is being generated from different templates. I just want my sidebar to be there on the main page.
https://github.com/swagger-api/swagger-ui
dist/index.html:
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Swagger UI</title>
<link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32" />
<link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16" />
<link href='css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
<link href='css/reset.css' media='print' rel='stylesheet' type='text/css'/>
<link href='css/print.css' media='print' rel='stylesheet' type='text/css'/>
<link href='css/bootstrap.min.css' media='print' rel='stylesheet' type='text/css'/>
<link href="css/simple-sidebar.css" media='print' rel='stylesheet' type='text/css'/>
<script src='lib/object-assign-pollyfill.js' type='text/javascript'></script>
<script src='lib/jquery-1.8.0.min.js' type='text/javascript'></script>
<script src='lib/jquery.slideto.min.js' type='text/javascript'></script>
<script src='lib/jquery.wiggle.min.js' type='text/javascript'></script>
<script src='lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
<script src='lib/handlebars-2.0.0.js' type='text/javascript'></script>
<script src='lib/js-yaml.min.js' type='text/javascript'></script>
<script src='lib/lodash.min.js' type='text/javascript'></script>
<script src='lib/backbone-min.js' type='text/javascript'></script>
<script src='swagger-ui.js' type='text/javascript'></script>
<script src='lib/highlight.9.1.0.pack.js' type='text/javascript'></script>
<script src='lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>
<script src='lib/jsoneditor.min.js' type='text/javascript'></script>
<script src='lib/marked.js' type='text/javascript'></script>
<script src='lib/swagger-oauth.js' type='text/javascript'></script>
<!-- Some basic translations -->
<!-- <script src='lang/translator.js' type='text/javascript'></script> -->
<!-- <script src='lang/ru.js' type='text/javascript'></script> -->
<!-- <script src='lang/en.js' type='text/javascript'></script> -->
<script type="text/javascript">
$(function () {
var url="http://localhost:8081/instagram.yml";
var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1) {
url = decodeURIComponent(url[1]);
} else {
url = "http://localhost:8081/instagram.yml";
}
hljs.configure({
highlightSizeThreshold: 5000
});
// Pre load translate...
if(window.SwaggerTranslator) {
window.SwaggerTranslator.translate();
}
window.swaggerUi = new SwaggerUi({
url: url,
dom_id: "swagger-ui-container",
supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
onComplete: function(swaggerApi, swaggerUi){
if(typeof initOAuth == "function") {
initOAuth({
clientId: "your-client-id",
clientSecret: "your-client-secret-if-required",
realm: "your-realms",
appName: "your-app-name",
scopeSeparator: ",",
additionalQueryStringParams: {}
});
}
if(window.SwaggerTranslator) {
window.SwaggerTranslator.translate();
}
},
onFailure: function(data) {
log("Unable to Load SwaggerUI");
},
docExpansion: "none",
jsonEditor: false,
defaultModelRendering: 'schema',
showRequestHeaders: false
});
window.swaggerUi.load();
function log() {
if ('console' in window) {
console.log.apply(console, arguments);
}
}
});
</script>
</head>
<body class="swagger-section">
<div id='header'>
<div class="swagger-ui-wrap">
<a id="logo" href="http://swagger.io">swagger</a>
<form id='api_selector'>
<div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>
<div class='input'><input placeholder="api_key" id="input_apiKey" name="apiKey" type="text"/></div>
<div class='input'><a id="explore" href="#">Explore</a></div>
</form>
</div>
</div>
<div id="sidebar-wrapper">
<ul class="sidebar-nav">
<li class="sidebar-brand">
<a href="#">Start Bootstrap</a>
</li>
<li>
<a href="#">Dashboard</a>
</li>
<li>
<a href="#">Shortcuts</a>
</li>
<li>
<a href="#">Overview</a>
</li>
<li>
<a href="#">Events</a>
</li>
<li>
<a href="#">About</a>
</li>
<li>
<a href="#">Services</a>
</li>
<li>
<a href="#">Contact</a>
</li>
</ul>
</div>
<div id="message-bar" class="swagger-ui-wrap"> </div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</body>
</html>
797
What is Swagger UI? Swagger UI, a part of Swagger, is an open source tool that generates a web page that documents the APIs generated by the Swagger specification. This UI presentation of the APIs is user friendly and easy to understand, with all logic complexity kept behind the screen.
To customize the style of the swagger page, you can pass custom CSS as the 'customCss' and 'customfavIcon' for Favicon property of the options to the setup function.
It's pretty easy to embed Swagger into an HTML page — just copy the code from the index. html file from the dist folder into your doc page (more or less). The latest version of Swagger has a more responsive, liquid design. It almost looks designed to be embedded into another site.
The index.html file is missing:
sidebar-wrapper containing the side barpage-content-wrapper containing what is on the right of the side barwrapper containing both sidebar-wrapper and page-content-wrapper
Here's an example (full working repo here: https://github.com/arno-di-loreto/stackoverflow-38377821-customize-swagger-ui-by-adding-a-simple-sidebar-in-the-html)
<body class="swagger-section">
<div id='header'>
<div class="swagger-ui-wrap">
<a id="logo" href="http://swagger.io"><img class="logo__img" alt="swagger" height="30" width="30" src="images/logo_small.png" /><span class="logo__title">swagger</span></a>
<!-- Bootstrap Simple Sidebar: Toggle button -->
<a href="#menu-toggle" class="btn btn-default" id="menu-toggle">Toggle Menu</a>
<form id='api_selector'>
<div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>
<div id='auth_container'></div>
<div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div>
</form>
</div>
</div>
<!-- Bootstrap Simple Sidebar: Global wrapper, contains sidebar and page -->
<div id="wrapper">
<!-- Bootstrap Simple Sidebar: Sidebar -->
<div id="sidebar-wrapper">
<ul class="sidebar-nav">
<li class="sidebar-brand">
<a href="#">
Start Bootstrap
</a>
</li>
<li>
<a href="#">Dashboard</a>
</li>
<li>
<a href="#">Shortcuts</a>
</li>
<li>
<a href="#">Overview</a>
</li>
<li>
<a href="#">Events</a>
</li>
<li>
<a href="#">About</a>
</li>
<li>
<a href="#">Services</a>
</li>
<li>
<a href="#">Contact</a>
</li>
</ul>
</div>
<!-- Bootstrap Simple Sidebar: Page wrapper -->
<div id="page-content-wrapper">
<div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</div>
</div>
<!-- Bootstrap Simple Sidebar: Menu Toggle Script -->
<script>
$("#menu-toggle").click(function(e) {
e.preventDefault();
$("#wrapper").toggleClass("toggled");
});
</script>
</body>
The repo https://github.com/arno-di-loreto/stackoverflow-38377821-customize-swagger-ui-by-adding-a-simple-sidebar-in-the-html provide 2 branches:
I had to modify some css and handlebar template to solve to bugs due to bootstrap integration in swagger ui (see commits list for details).
Full step by step instructions
First and foremost: never edit files in dist folder directly, you have to work with source files in src:
src/main/html/css/
src/main/less, once compiled the css files go to src/main/html/css/
src/main/htmlcontains the main html file (index.html)Each step correspond to a commit in the example repository.
Project init
git clone https://github.com/swagger-api/swagger-ui
cd swagger-uinpm installgulp dev
Adding simple-sidebar.css and bootstrap.min.css to the project (commit)
simple-sidebar.css and bootstrap.min.css to src/main/html/css/
Modify src/main/html/index.html to add a reference to these 2 css files after swagger-ui css:
Add bootstrap sidebar (commit)
src/main/html/index.html:
<div id="page-content-wrapper"> div<div id="wrapper"> div<div id="sidebar-wrapper"> ... </div>) on top of <div id="wrapper">
</body> Once this is done, you have:
Fix Swagger UI container width (commit)
src/main/template/main.handlebars:
id='resources_container' use a class container, rename this class to sw-container
Fix white padding around page (commit)
padding in #page-content-wrapper on line 47 and 121Fix header green background size
- To fix this bug you have to modify a screen.less in src/main/less/
- This folder contains all less files which will be used to create css files for Swagger UI
- I choose to remove height:23 and slightly change padding to solve this bug
Once this is donne you have (branch v1.0_header_in_page):
Move SwaggerUI header on top and fix it (commit, branch v1.1_header_above_sidebar)
src/main/html/index.html, move the <div id='header'> just before the <div id="wrapper">
To fix it modify src/main/less/screen.less to add these values to #header:
position: fixed; top: 0px; margin: auto; z-index: 100000; width: 100%;
src/main/html/css/simple-sidebar.css to add padding-top: 50px; to #wrapper
113
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
