怎样在Linux上定制Swagger API文档样式
作者：袖梨
2026-07-09
在Linux上定制Swagger API文档样式，可以通过以下步骤实现：
1. 安装Swagger工具
首先，确保你已经安装了Swagger工具。你可以使用以下命令来安装Swagger：
sudo apt-get updatesudo apt-get install swagger-ui-express2. 创建Swagger配置文件
创建一个Swagger配置文件（通常是swagger.json），并在其中定义你的API文档。你可以手动编写这个文件，或者使用Swagger Editor来生成。
{"swagger": "2.0","info": {"title": "My API","description": "API documentation for My API","version": "1.0.0"},"host": "api.example.com","basePath": "/v1","schemes": ["https"],"paths": {"/users": {"get": {"summary": "Get a list of users","responses": {"200": {"description": "A list of users","schema": {"type": "array","items": {"$ref": "#/definitions/User"}}}}}}},"definitions": {"User": {"type": "object","properties": {"id": {"type": "integer"},"name": {"type": "string"}}}}}3. 定制Swagger UI样式
Swagger UI提供了多种方式来定制样式。你可以通过修改CSS文件或使用Swagger UI的自定义扩展来实现。
方法一：修改CSS文件
- 找到Swagger UI的CSS文件，通常位于
node_modules/swagger-ui-dist/swagger-ui.css。 - 复制这个文件到你项目的静态资源目录中，并重命名为
custom.css。 - 修改
custom.css文件中的样式，以满足你的需求。
例如，修改背景颜色：
.swagger-ui .topbar {background-color: #f0f0f0;}方法二：使用Swagger UI的自定义扩展
你可以创建一个自定义的Swagger UI扩展来修改样式或添加新的功能。
- 创建一个新的JavaScript文件，例如
custom-swagger-ui.js。 - 在这个文件中编写你的自定义代码。
例如，修改API列表的样式：
window.onload = function() {const ui = SwaggerUIBundle({url: "swagger.json",dom_id: '#swagger-ui',deepLinking: true,presets: [SwaggerUIBundle.presets.apis,SwaggerUIStandalonePreset],plugins: [SwaggerUIBundle.plugins.DownloadUrl],layout: "StandaloneLayout"});// 自定义样式const apiList = ui.getDomById('apis');if (apiList) {apiList.style.backgroundColor = '#f0f0f0';}};- 在HTML文件中引入这个自定义脚本：
<!DOCTYPE html><html><head><title>Swagger UI</title><link rel="stylesheet" type="text/css" href="node_modules/swagger-ui-dist/swagger-ui.css"><link rel="stylesheet" type="text/css" href="custom.css"></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 src="custom-swagger-ui.js"></script></body></html>4. 启动Swagger UI
最后，启动Swagger UI来查看你的定制化API文档。
node server.js其中server.js是你的Express服务器文件，内容如下：
const express = require('express');const swaggerUi = require('swagger-ui-express');const YAML = require('yamljs');const app = express();const swaggerDocument = YAML.load('./swagger.json');app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));app.listen(3000, () => {console.log('Server is running on http://localhost:3000');});通过以上步骤，你可以在Linux上定制Swagger API文档样式。根据你的需求，你可以进一步扩展和修改这些步骤。
