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

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

所以我正在尝试在 swagger-ui 首页上制作一个导航面板侧边栏。我正在使用 http://startbootstrap.com/template-overviews/simple-sidebar/ 简单的侧边栏。我尝试将该代码（+ css 文件）放在 swagger-ui 的 dist 文件夹中，然后在我的 dist/index.html 中，我尝试添加它但是它没有正确显示。我认为这是因为 swagger 内容是从不同的模板生成的。我只想让我的侧边栏出现在主页上。

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

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

    </body>
    </html>

缺少 index.html 文件：

  • ID 为 sidebar-wrapper 的 div 包含边栏
  • ID 为 page-content-wrapper 的 div 包含侧边栏右侧的内容
  • ID 为 wrapper 的 div 包含 sidebar-wrapper 和 page-content-wrapper

这是一个例子（这里是完整的工作仓库：https://github.com/arno-di-loreto/Whosebug-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>

repo https://github.com/arno-di-loreto/Whosebug-38377821-customize-swagger-ui-by-adding-a-simple-sidebar-in-the-html 提供 2 个分支：

  • v1.0_header_in_page: SwaggerUI绿色header在页面中，未修复
  • v1.1_header_above_sidebar: SwaggerUI green header 在侧边栏上方，固定

我不得不修改一些 css 和车把模板来解决由于 bootstrap 集成在 swagger ui 中的错误（详情请参阅提交列表）。

完整的分步说明

首先：切勿直接编辑 dist 文件夹中的文件，您必须使用 src:

中的源文件
  • css:
    • 您可以将自己的 css 添加到 src/main/html/css/
    • SwaggerUI 的 css 是 build 在 src/main/less 中使用较少的文件，编译 css 文件后转到 src/main/html/css/
  • html:
    • `src/main/template 包含把手 HTML 模板（除了 SwaggerUI 的 header 和页脚之外的所有内容）
    • src/main/html包含主要 html 文件 (index.html)

每个步骤对应于 example repository 中的一个提交。

项目初始化

  • 克隆 Swagger UI 存储库：git clone https://github.com/swagger-api/swagger-ui
  • 下载依赖：
    • cd swagger-ui
    • npm install
  • 启动开发模式：gulp dev
    • 此build 应用程序，在端口8080 上启动一个web 服务器。如果对代码进行了修改，浏览器将自动重新加载

将simple-sidebar.css和bootstrap.min.css添加到项目中(commit)

  • 将simple-sidebar.css和bootstrap.min.css复制到src/main/html/css/

  • 修改src/main/html/index.html在swagger-ui后添加对这2个css文件的引用 css:

添加 bootstrap 边栏 (commit)

  • 修改src/main/html/index.html：
    • 将 body 中的所有组件包含在 <div id="page-content-wrapper"> div
      • 中
    • 括在<div id="wrapper">div
    • 在 <div id="wrapper">
      • 之上添加边栏 (<div id="sidebar-wrapper"> ... </div>)
    • 在 </body>
      • 之前添加菜单切换脚本

一旦完成，您将拥有：

  • 功能性侧边栏
  • Swagger UI header 在侧边栏右侧
  • 很少有 css 错误，例如：
    • 绿色背景header尺寸错误
    • 页面周围的白色填充（在侧边栏的右侧）
    • Swagger ui 主容器太大

修复 Swagger UI 容器宽度 (commit)

  • 要修复 swagger 容器宽度，您需要修改 src/main/template/main.handlebars：
    • 此文件是主要模板，包含信息部分、div（API 描述所在的位置）和页脚
    • divid='resources_container'使用一个classcontainer，将这个class重命名为sw-container

修复页面周围的白色填充 (commit)

  • 白色填充来自``文件：
    • 您只需删除第 47 行 #page-content-wrapper 中的 padding 和第 121 行

修正header绿色背景尺寸 - 要修复此错误，您必须修改 src/main/less/ 中的 screen.less - 此文件夹包含所有 less 文件，这些文件将用于为 Swagger UI 创建 css 文件 - 我选择删除 height:23 并稍微更改填充以解决此错误

一旦完成，您将拥有（分支 v1.0_header_in_page）：

  • 功能性侧边栏
  • 侧边栏右侧的 Swagger ui
  • 正确显示

将 SwaggerUI header 移到顶部并修复它 (commit, branch v1.1_header_above_sidebar)

  • 要将 header 放在顶部修改 src/main/html/index.html，将 <div id='header'> 移到 <div id="wrapper">
    • 之前

  • 要修复它修改 src/main/less/screen.less 将这些值添加到 #header:

    位置：固定； 顶部：0px； 保证金：自动； z-index: 100000; 宽度：100%；

  • 为了避免内容被隐藏在header后面修改src/main/html/css/simple-sidebar.css添加padding-top: 50px;到#wrapper