正文

学会自定义SwaggerUI，打造个性化API文档界面

/0 浏览量
1025

在开发API时，一个清晰、易用的文档界面对于开发者来说至关重要。SwaggerUI是一个流行的API文档和测试工具，它能够将Swagger定义的API文档转换为交互式的界面。通过自定义SwaggerUI，你可以打造出符合自己项目风格的API文档界面。下面，我将详细介绍如何学会自定义SwaggerUI，并打造一个个性化的API文档界面。

一、了解SwaggerUI

SwaggerUI是一个基于HTML5、CSS3和JavaScript的库，它可以将Swagger定义的API文档转换为交互式的界面。SwaggerUI支持多种语言和框架，如Java、Python、Node.js等。

二、安装SwaggerUI

首先，你需要安装SwaggerUI。以下是在不同环境中安装SwaggerUI的方法：

2.1 在Node.js项目中安装

npm install swagger-ui-express --save

2.2 在Java项目中安装

mvn add-dependency org.springdoc:springdoc-openapi-ui:1.6.6

2.3 在Python项目中安装

pip install flasgger

三、自定义SwaggerUI

3.1 修改默认样式

SwaggerUI提供了一套默认的样式，但你可以根据自己的需求进行修改。以下是在HTML文件中修改样式的示例：

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" type="text/css" href="node_modules/swagger-ui/dist/swagger-ui.css">
  <style>
    .swagger-ui .topbar {
      background-color: #f8f9fa;
    }
    .swagger-ui .info pre {
      background-color: #f5f5f5;
    }
  </style>
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="node_modules/swagger-ui/dist/swagger-ui-bundle.js"></script>
  <script src="node_modules/swagger-ui/dist/swagger-ui-standalone-preset.js"></script>
  <script>
    const ui = SwaggerUIBundle({
      url: '/swagger.json',
      dom_id: '#swagger-ui',
      layout: 'StandaloneLayout',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIBundle.presets.doc
      ],
      plugins: [
        SwaggerUIBundle.plugins.DownloadLink
      ],
      layout: 'StandaloneLayout',
      docExpansion: 'list',
      deepLinking: true,
      showRequestHeaders: true
    });
  </script>
</body>
</html>

3.2 添加自定义图标

SwaggerUI支持自定义图标，你可以通过修改swagger-ui.css文件来实现。以下是在swagger-ui.css中添加自定义图标的示例：

/* 添加自定义图标 */
@font-face {
  font-family: 'my-icon';
  src: url('my-icon.eot');
  src: url('my-icon.eot?#iefix') format('embedded-opentype'),
       url('my-icon.woff2') format('woff2'),
       url('my-icon.woff') format('woff'),
       url('my-icon.svg#my-icon') format('svg');
}

/* 使用自定义图标 */
.swagger-ui .topbar .branding > img {
  background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==');
}

3.3 添加自定义脚本

SwaggerUI支持自定义脚本，你可以通过在HTML文件中添加<script>标签来实现。以下是在HTML文件中添加自定义脚本的示例：

<script>
  // 自定义脚本
  function myCustomFunction() {
    console.log('Hello, SwaggerUI!');
  }
</script>

四、总结

通过以上步骤，你学会了如何自定义SwaggerUI，并打造一个个性化的API文档界面。自定义SwaggerUI可以帮助你更好地展示API文档，提高开发效率。希望这篇文章对你有所帮助！

-- 展开阅读全文 --