Angular Angular - 4 months ago 177
HTML Question

customize swagger-ui by adding a simple sidebar in the html

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

enter image description here

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">&nbsp;</div>

<div id="swagger-ui-container" class="swagger-ui-wrap"></div>

</body>
</html>

Answer

The index.html file is missing:

  • A div with id sidebar-wrapper containing the side bar
  • A div with id page-content-wrapper containing what is on the right of the side bar
  • A div with id wrapper 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>&nbsp;</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:

  • v1.0_header_in_page: The SwaggerUI green header is in the page and not fixed enter image description here
  • v1.1_header_above_sidebar: The SwaggerUI green header is above the sidebar and fixed enter image description here

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:

  • css:
    • You can add your own css to src/main/html/css/
    • SwaggerUI's css are build using less files in src/main/less, once compiled the css files go to src/main/html/css/
  • html:
    • `src/main/template contains handlebar HTML templates (it's everything except the header and footer of SwaggerUI)
    • src/main/htmlcontains the main html file (index.html)

Each step correspond to a commit in the example repository.

Project init

  • Clone Swagger UI repository: git clone https://github.com/swagger-api/swagger-ui
  • Download dependencies:
    • cd swagger-ui
    • npm install
  • Start dev mode: gulp dev
    • This build the application, launch a web server on port 8080. If modifications are done to the code, the browser will reload automatically

Adding simple-sidebar.css and bootstrap.min.css to the project (commit)

  • Copy 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)

  • Modify src/main/html/index.html:
    • Enclose all components which are in the body in a <div id="page-content-wrapper"> div
    • Enclose in a <div id="wrapper"> div
    • Add the sidebar (<div id="sidebar-wrapper"> ... </div>) on top of <div id="wrapper">
    • Add the Menu Toggle Script just before </body>

Once this is done, you have:

  • A functionnal sidebar
  • A Swagger UI header on the right on the sidebar
  • Few css bugs like:
    • Green background header wrong size
    • White padding around the page (on the right of the sidebar)
    • Swagger ui main container too large

Fix Swagger UI container width (commit)

  • To fix swagger container width you need to modify src/main/template/main.handlebars:
    • This file is the main template containing the info section, the div where the API description will go and the footer
    • The div id='resources_container' use a class container, rename this class to sw-container

Fix white padding around page (commit)

  • The white padding comes from the `` file:
    • You just need to remove both padding in #page-content-wrapper on line 47 and 121

Fix 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):

  • A functionnal sidebar
  • A Swagger ui on the right of the sidebar
  • A correct display

Move SwaggerUI header on top and fix it (commit, branch v1.1_header_above_sidebar)

  • To put the header on top modify 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%;

  • To avoid content to be hidden behind the header modify src/main/html/css/simple-sidebar.css to add padding-top: 50px; to #wrapper
Comments