阅读量:3
Ubuntu下Swagger UI自定义方法
1. 基础环境准备
在自定义前，需安装Node.js、npm（Node包管理器）和Docker（可选，用于容器化部署）。通过以下命令安装：
sudo apt update
sudo apt install nodejs npm docker.io
2. 安装Swagger UI依赖
方式一：通过npm安装（适用于Node.js项目）
# 全局安装swagger-ui-express（Express中间件）
sudo npm install -g swagger-ui-express
# 进入项目目录，初始化项目并安装依赖
mkdir swagger-ui-project && cd swagger-ui-project
npm init -y
npm install express swagger-ui-express yamljs
方式二：通过Docker安装（快速部署）
# 拉取Swagger UI官方镜像
docker pull swaggerapi/swagger-ui-express
# 运行容器，映射端口8080
docker run -d -p 8080:8080 swaggerapi/swagger-ui-express
3. 配置Swagger文档
创建Swagger规范文件（swagger.yaml或swagger.json），定义API信息（如路径、方法、参数）。示例swagger.yaml：
swagger: '2.0'
info:
title: Sample API
description: A demo API for Swagger UI customization
version: '1.0.0'
paths:
/users:
get:
summary: List all users
responses:
'200':
description: An array of users
schema:
type: array
items:
$ref: '#/definitions/User'
definitions:
User:
type: object
properties:
id:
type: integer
name:
type: string
4. 集成Swagger UI到应用（Node.js项目）
创建app.js文件，使用swagger-ui-express集成Swagger文档：
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
// 加载Swagger文档
const swaggerDocument = YAML.load('./swagger.yaml');
const app = express();
const PORT = process.env.PORT || 3000;
// 配置Swagger UI选项（自定义入口）
const customOptions = {
deepLinking: true, // 启用深度链接
presets: [
swaggerUi.presets.apis, // 默认API预设
swaggerUi.presets.promises // Promise支持
],
plugins: [
swaggerUi.plugins.DownloadUrl // 添加下载URL插件
],
layout: "StandaloneLayout" // 使用独立布局
};
// 挂载Swagger UI到/api-docs路径
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, customOptions));
app.listen(PORT, () => {
console.log(`Swagger UI running at http://localhost:${PORT}/api-docs`);
});
5. 常见自定义方式
（1）通过配置选项调整UI行为
在swaggerUi.setup()中传入配置对象，可调整以下参数：
deepLinking：启用URL深度链接，支持直接跳转到指定API。docExpansion：设置文档默认展开状态（none/list/full）。defaultModelsExpandDepth：默认展开的模型深度（0-10）。operationsSorter：操作排序方式（alpha按字母排序，method按HTTP方法排序）。
示例：
const customOptions = {
docExpansion: 'list', // 默认展开所有操作
operationsSorter: 'alpha', // 按字母排序操作
defaultModelsExpandDepth: 2 // 默认展开模型到第2层
};
（2）自定义CSS样式
方法一：通过配置注入自定义CSS
在application.yml（Spring Boot项目）或customOptions中添加customCss字段：
springdoc:
swagger-ui:
custom-css: |
.swagger-ui .topbar { background-color: #1E3A8A; }
.swagger-ui .topbar .download-url-wrapper { display: none; }
方法二：创建自定义CSS文件
- 在项目静态目录（如
src/main/resources/static/）下创建custom-swagger.css：
/* 修改顶部栏背景色 */
.swagger-ui .topbar {
background-color: #2c3e50 !important;
}
/* 隐藏顶部下载输入框 */
.swagger-ui .topbar .download-url-wrapper {
display: none !important;
}
/* 修改标题样式 */
.swagger-ui .info .title {
color: #2c3e50;
font-size: 36px;
}
/* 修改Try it out按钮 */
.swagger-ui .btn.try-out__btn {
background-color: #3498db;
border-color: #3498db;
}
- 在配置中引用该CSS文件：
springdoc:
swagger-ui:
custom-css-url: /custom-swagger.css
（3）完全自定义HTML页面
创建自定义HTML文件（如custom-swagger.html），引入Swagger UI的JS/CSS文件并配置：
html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>Custom Swagger UItitle>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css">
<style>
body { margin: 0; padding: 0; }
#custom-header {
background-color: #2c3e50;
color: white;
padding: 20px;
text-align: center;
}
#swagger-ui { max-width: 1200px; margin: 0 auto; }
style>
head>
<body>
<div id="custom-header">
<h1>My Custom API Docsh1>
<p>Version 1.0.0p>
div>
<div id="swagger-ui">div>
<script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js">script>
<script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-standalone-preset.js">script>
<script>
window.onload = function() {
const ui = SwaggerUI({
url: "/v3/api-docs", // 指向后端API文档地址
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUI.presets.apis,
SwaggerUI.SwaggerUIStandalonePreset
],
plugins: [
SwaggerUI.plugins.DownloadUrl
],
layout: "StandaloneLayout",
theme: { // 自定义主题（可选）
colors: {
primary: '#2c3e50'
}
}
});
window.ui = ui;
};
script>
body>
html>
（4）使用第三方主题
通过springdoc.swagger-ui.syntax-highlight.theme配置语法高亮主题（如monokai、github）：
springdoc:
swagger-ui:
syntax-highlight:
theme: monokai
（5）添加自定义Logo
在Swagger配置的info部分添加HTML内容，引用Logo图片：
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("My API")
.version("1.0.0")
.description("
My Custom API Documentation")
);
}
将Logo图片（logo.png）放置在src/main/resources/static/目录下。
6. 运行与验证
- Node.js项目：运行
node app.js，访问http://localhost:3000/api-docs查看自定义效果。 - Docker项目：运行
docker run -d -p 8080:8080 swaggerapi/swagger-ui-express，访问http://localhost:8080查看。
注意事项
- 自定义CSS时，优先使用
!important覆盖默认样式（避免被默认样式覆盖）。 - 完全自定义HTML页面时，需确保正确引入Swagger UI的JS/CSS文件（版本需与依赖一致）。
- 生产环境中，建议通过Nginx或Apache反向代理Swagger UI，并配置HTTPS以提高安全性。
以上就是关于“Ubuntu下Swagger UI如何自定义”的相关介绍，筋斗云是国内较早的云主机应用的服务商，拥有10余年行业经验，提供丰富的云服务器、租用服务器等相关产品服务。云服务器资源弹性伸缩，主机vCPU、内存性能强悍、超高I/O速度、故障秒级恢复；电子化备案，提交快速，专业团队7×24小时服务支持！
简单好用、高性价比云服务器租用链接：https://www.jindouyun.cn/product/cvm