通过在html中添加一个简单的侧边栏来自定义swagger-ui

Question

So I'm trying to make a navigation panel sidebar on the swagger-ui front page. 所以我试图在swagger-ui头版上制作导航面板侧边栏。 I'm using the http://startbootstrap.com/template-overviews/simple-sidebar/ simple sidebar. 我正在使用http://startbootstrap.com/template-overviews/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. 我尝试将该代码（+ css文件）放在swagger-ui的dist文件夹中然后，在我的dist / index.html中，我尝试添加它但它没有正确显示。 I think this is because swagger content is being generated from different templates. 我认为这是因为swagger内容是从不同的模板生成的。 I just want my sidebar to be there on the main page. 我只想让我的侧边栏在主页上。

https://github.com/swagger-api/swagger-ui https://github.com/swagger-api/swagger-ui

dist/index.html: 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 1

The index.html file is missing: index.html文件丢失：

A div with id sidebar-wrapper containing the side bar 包含侧栏的id sidebar-wrapper div
A div with id page-content-wrapper containing what is on the right of the side bar 包含id page-content-wrapper div，包含侧栏右侧的内容
A div with id wrapper containing both sidebar-wrapper and page-content-wrapper 带有id wrapper的div，包含sidebar-wrapper和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 ) 这是一个例子（完整的工作回购： 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: 回购https://github.com/arno-di-loreto/stackoverflow-38377821-customize-swagger-ui-by-adding-a-simple-sidebar-in-the-html提供了2个分支：

v1.0_header_in_page: The SwaggerUI green header is in the page and not fixed v1.0_header_in_page：SwaggerUI绿色标题位于页面中而不是固定的
v1.1_header_above_sidebar: The SwaggerUI green header is above the sidebar and fixed v1.1_header_above_sidebar：SwaggerUI绿色标题位于侧边栏上方并已修复

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). 我不得不修改一些css和handlebar模板以解决由于swagger ui中的bootstrap集成而导致的错误（有关详细信息，请参阅提交列表）。

Full step by step instructions 完整的分步说明

First and foremost: never edit files in dist folder directly, you have to work with source files in src : 首先：永远不要直接编辑dist文件夹中的文件，你必须使用src源文件：

css: CSS：
- You can add your own css to src/main/html/css/ 你可以将自己的css添加到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/ SwaggerUI的css是使用src/main/less较少的文件构建的，一旦编译完css文件就转到src/main/html/css/
html: HTML：
- `src/main/template contains handlebar HTML templates (it's everything except the header and footer of SwaggerUI) `src / main / template包含车把HTML模板（除了SwaggerUI的页眉和页脚之外的所有内容）
- src/main/html contains the main html file (index.html) src/main/html包含主要的html文件（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 Clone Swagger UI存储库： git clone https://github.com/swagger-api/swagger-ui
Download dependencies: 下载依赖项：
- cd swagger-ui
- npm install
Start dev mode: gulp dev 启动开发模式： 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 这将构建应用程序，在端口8080上启动Web服务器。如果对代码进行了修改，浏览器将自动重新加载

Adding simple-sidebar.css and bootstrap.min.css to the project ( commit ) 将simple-sidebar.css和bootstrap.min.css添加到项目（ commit ）

Copy simple-sidebar.css and bootstrap.min.css to src/main/html/css/ 将simple-sidebar.css和bootstrap.min.css复制到src/main/html/css/
Modify src/main/html/index.html to add a reference to these 2 css files after swagger-ui css: 修改src/main/html/index.html以在swagger-ui css之后添加对这2个css文件的引用：

Add bootstrap sidebar ( commit ) 添加bootstrap侧边栏（提交）

Modify src/main/html/index.html : 修改src/main/html/index.html ：
- Enclose all components which are in the body in a <div id="page-content-wrapper"> div 将所有组件放在<div id="page-content-wrapper"> div中
- Enclose in a <div id="wrapper"> div 包含在<div id="wrapper"> div中
- Add the sidebar ( <div id="sidebar-wrapper"> ... </div> ) on top of <div id="wrapper"> 添加侧边栏（ <div id="sidebar-wrapper"> ... </div>的顶部<div id="wrapper">
- Add the Menu Toggle Script just before </body> 在</body>之前添加菜单切换脚本

Once this is done, you have: 完成后，您有：

A functionnal sidebar 功能侧边栏
A Swagger UI header on the right on the sidebar 侧栏右侧的Swagger UI标题
Few css bugs like: 很少有css错误：
- Green background header wrong size 绿色背景标题错误的大小
- White padding around the page (on the right of the sidebar) 页面周围的白色填充（侧边栏右侧）
- Swagger ui main container too large Swagger ui主容器太大了

Fix Swagger UI container width ( commit ) 修复Swagger UI容器宽度（提交）

To fix swagger container width you need to modify src/main/template/main.handlebars : 要修复swagger容器宽度，您需要修改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 此文件是包含信息部分的主模板，API描述所在的div和页脚
- The div id='resources_container' use a class container , rename this class to sw-container div id='resources_container'使用类container ，将此类重命名为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 您只需要在#page-content-wrapper 47行和第121行的#page-content-wrapper删除两个padding

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 修复标题绿色背景大小 - 要修复此错误，您必须修改src/main/less/的screen.less此文件夹包含将用于为Swagger UI创建css文件的所有较少文件 - 我选择删除高度： 23并略微更改填充以解决此错误

Once this is donne you have (branch v1.0_header_in_page ): 一旦这是donne你有（分支v1.0_header_in_page ）：

A functionnal sidebar 功能侧边栏
A Swagger ui on the right of the sidebar 侧边栏右侧的Swagger ui
A correct display 正确显示

Move SwaggerUI header on top and fix it ( commit , branch v1.1_header_above_sidebar ) 将SwaggerUI标头移到顶部并修复它（ 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"> 要将标题放在顶部修改src/main/html/index.html ，请在<div id="wrapper">之前移动<div id='header'> <div id="wrapper">
To fix it modify src/main/less/screen.less to add these values to #header : 要修复它，请修改src/main/less/screen.less以将这些值添加到#header ：
position: fixed; 位置：固定; top: 0px; 顶部：0px; margin: auto; 保证金：自动; z-index: 100000; z-index：100000; width: 100%; 宽度：100％;
To avoid content to be hidden behind the header modify src/main/html/css/simple-sidebar.css to add padding-top: 50px; 为了避免将内容隐藏在标题后面，请修改src/main/html/css/simple-sidebar.css以添加padding-top: 50px; to #wrapper 到#wrapper

通过在html中添加一个简单的侧边栏来自定义swagger-ui

问题描述

1 个解决方案

解决方案1
5 已采纳 2016-07-24 17:58:06

通过在html中添加一个简单的侧边栏来自定义swagger-ui

问题描述

1 个解决方案

解决方案1 5 已采纳 2016-07-24 17:58:06

解决方案1
5 已采纳 2016-07-24 17:58:06