Swagger UI 项目安装与部署完全指南

柏纲墩Dean

于 2025-06-01 09:03:52 发布

阅读量342

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00815/article/details/148360735

Swagger UI 项目安装与部署完全指南

swagger-ui 项目地址: https://gitcode.com/gh_mirrors/swa/swagger-ui

前言

Swagger UI 是一款流行的 API 文档可视化工具，能够将 OpenAPI 规范文档转换为美观、交互式的 Web 界面。本文将全面介绍 Swagger UI 的多种安装和部署方式，帮助开发者根据项目需求选择最适合的方案。

核心安装方式

1. NPM 包管理安装

Swagger UI 提供了三个核心 NPM 包：

swagger-ui：适用于使用 Webpack、Browserify 等模块打包工具的现代 JavaScript 项目
swagger-ui-dist：适合需要直接提供静态资源的服务端项目
swagger-ui-react：React 专用版本

1.1 swagger-ui 使用示例

import SwaggerUI from 'swagger-ui'
import 'swagger-ui/dist/swagger-ui.css'

SwaggerUI({
  dom_id: '#api-container',
  url: '/api/openapi.json'
})

这种方式允许开发者灵活定制界面，并与其他前端框架集成。

1.2 swagger-ui-dist 使用场景

当需要快速部署静态资源时：

const path = require('path')
const express = require('express')
const swaggerUiDist = require('swagger-ui-dist')

const app = express()
app.use('/api-docs', express.static(swaggerUiDist.absolutePath()))

容器化部署方案

2. Docker 快速部署

Swagger UI 提供了官方 Docker 镜像，支持多种配置方式：

2.1 基础运行命令

docker run -p 8080:8080 swaggerapi/swagger-ui

2.2 自定义配置

# 挂载本地规范文件
docker run -p 80:8080 -v /local/path:/spec -e SWAGGER_JSON=/spec/api.json swaggerapi/swagger-ui

# 使用远程规范文件
docker run -p 80:8080 -e SWAGGER_JSON_URL=https://api.example.com/openapi.json swaggerapi/swagger-ui

2.3 高级配置选项

BASE_URL：修改基础路径
PORT：自定义服务端口
EMBEDDING：控制 iframe 嵌入权限
VALIDATOR_URL：设置验证器地址

无构建环境解决方案

3. CDN 直接引用

对于简单项目或快速原型，可以直接使用 CDN 资源：

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest/swagger-ui.css">
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@latest/swagger-ui-bundle.js"></script>
  <script>
    window.onload = () => {
      SwaggerUIBundle({
        url: "/api/openapi.json",
        dom_id: '#swagger-ui'
      });
    };
  </script>
</body>
</html>