Swagger UI 项目安装与部署指南

尤辰城Agatha

于 2025-06-01 09:04:14 发布

阅读量429

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00254/article/details/148360846

Swagger UI 项目安装与部署指南

swagger-ui Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API. 项目地址: https://gitcode.com/gh_mirrors/sw/swagger-ui

前言

Swagger UI 是一个流行的 API 文档可视化工具，能够将 OpenAPI/Swagger 规范文档以美观、交互式的网页形式呈现。本文将详细介绍 Swagger UI 的多种安装和部署方式，帮助开发者根据项目需求选择最适合的方案。

核心安装方式

NPM 包安装（推荐）

对于现代前端项目，推荐使用 NPM 包管理方式进行安装。Swagger UI 提供了三个核心 NPM 包：

swagger-ui：适用于使用 Webpack、Browserify 等模块打包工具的项目
swagger-ui-react：专为 React 项目优化的版本
swagger-ui-dist：包含可直接部署的静态资源文件

安装命令

# 基础版本
npm install swagger-ui

# React 专用版本
npm install swagger-ui-react

# 静态资源版本
npm install swagger-ui-dist

基础使用示例

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

SwaggerUI({
  dom_id: '#swagger-container',
  url: 'https://example.com/api-spec.json'
})

各包适用场景对比

| 包名 | 适用场景 | 特点 | |------|---------|------| | swagger-ui | 现代前端项目 | 支持模块化导入，可按需打包 | | swagger-ui-react | React 项目 | 提供 React 组件形式 | | swagger-ui-dist | 快速部署 | 包含预构建的静态资源 |

Docker 容器部署

对于需要快速部署或微服务架构的项目，Docker 是最便捷的选择。

基础运行命令

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

高级配置选项

自定义规范文件：

docker run -p 80:8080 -e SWAGGER_JSON=/data/swagger.json -v /local/path:/data swaggerapi/swagger-ui

远程规范文件：

docker run -p 80:8080 -e SWAGGER_JSON_URL=https://example.com/api.json swaggerapi/swagger-ui

修改基础路径：

docker run -p 80:8080 -e BASE_URL=/api-docs swaggerapi/swagger-ui

端口配置：

docker run -p 80:80 -e PORT=80 swaggerapi/swagger-ui

安全配置：

docker run -p 80:8080 -e EMBEDDING=true swaggerapi/swagger-ui

CDN 直接引用

对于简单的演示或快速集成，可以使用 CDN 方式直接引入：

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

完整功能版（含顶部导航）

<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-standalone-preset.js"></script>
<script>
  window.ui = SwaggerUIBundle({
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    layout: "StandaloneLayout"
  });
</script>