Ubuntu Swagger如何进行自定义配置

Ubuntu 上 Swagger 自定义配置指南

一 前置准备

• 在 Ubuntu 上，Swagger/OpenAPI 的自定义通常分为两类：一是基于 Node.js + Express 托管 Swagger UI，二是 Spring Boot 项目内嵌 Swagger2/Swagger UI。
• 若采用 Node.js 方案，先安装 Node.js 与 npm，再安装相关包（如 swagger-ui-express、可选的 yamljs 用于加载 YAML 规范）：
  • 安装 Node.js 与 npm：sudo apt update && sudo apt install -y nodejs npm
  • 全局或本地安装：npm i -D swagger-ui-express yamljs
• 若采用 Spring Boot 方案，直接在项目中引入 springfox-swagger2 与 springfox-swagger-ui 依赖即可。

二 方案一 Node.js Express 集成与 UI 自定义

• 准备规范文件：创建 swagger.yaml 或 swagger.json（示例为 YAML）：
  • swagger: ‘2.0’
  • info:
    • title: Sample API
    • description: A sample API
    • version: 1.0.0
  • paths:
    • /users:
      • get:
        • summary: List all users
        • responses:
          • ‘200’:
            • description: An array of users
• 托管 Swagger UI：使用 swagger-ui-express 提供页面与接口规范。
  • 代码示例（app.js）：
    • const express = require(‘express’);
    • const swaggerUi = require(‘swagger-ui-express’);
    • const YAML = require(‘yamljs’);
    • const swaggerDocument = YAML.load(‘./swagger.yaml’);
    • const app = express();
    • app.use(‘/api-docs’, swaggerUi.serve, swaggerUi.setup(swaggerDocument, { deepLinking: true, presets: [swaggerUi.presets.apis, swaggerUi.presets.promises], plugins: [swaggerUi.plugins.DownloadUrl], layout: ‘StandaloneLayout’ }));
    • const port = process.env.PORT || 3000;
    • app.listen(port, () => console.log(Server running at http://localhost:${port}/api-docs));
• 运行与访问：node app.js，浏览器打开 http://localhost:3000/api-docs。
• 常用 UI 选项：
  • deepLinking：启用锚点定位到具体接口/模型。
  • presets/plugins：启用预设与插件（如 DownloadUrl 提供下载链接）。
  • layout：布局样式（如 StandaloneLayout）。

三 方案二 Spring Boot 项目内嵌 Swagger 配置

• 引入依赖（Maven 示例）：
  • io.springfox:springfox-swagger2:2.9.2
  • io.springfox:springfox-swagger-ui:2.9.2
• 配置类示例（SwaggerConfig.java）：
  • @Configuration
  • @EnableSwagger2
  • public class SwaggerConfig {
    • @Value(“${swagger.enabled:true}”)
    • private boolean enabled;
    • @Bean
    • public Docket createRestApi() {
      • return new Docket(DocumentationType.SWAGGER_2)
        • .enable(enabled)
        • .apiInfo(apiInfo())
        • .select()
        • .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
        • .paths(PathSelectors.any())
        • .build()
        • .securitySchemes(securitySchemes()) .securityContexts(securityContexts());
    • }
    • private ApiInfo apiInfo() { … } // 自定义标题、描述、版本、联系人等
    • private List securitySchemes() { … } // 如 ApiKey 在请求头
    • private List securityContexts() { … }
    • }
• 常用自定义点：
  • Docket 选择要扫描的包/类/方法（如 basePackage、withMethodAnnotation(ApiOperation.class)）。
  • paths 过滤路径（如正则匹配 /api/）。
  • securitySchemes + securityContexts 配置 API Key/JWT 等认证方式。
  • 通过 @Value(“${swagger.enabled}”) 控制是否启用文档（便于生产关闭）。

四 部署与运维建议

• 使用 Docker 快速托管 Swagger UI（适合静态托管或演示）：
  • 拉取镜像：docker pull swaggerapi/swagger-ui-express
  • 运行容器：docker run -p 8080:8080 swaggerapi/swagger-ui-express
  • 访问 http://localhost:8080 查看 UI（如需加载本地规范，可通过卷挂载或改造容器启动命令实现）。
• 生产建议：
  • 仅在内网或测试环境开启文档，生产可通过配置关闭（如 Spring Boot 的 swagger.enabled=false）。
  • 将规范文件纳入版本控制，与代码同步更新；对外只暴露文档页面，避免泄露内部实现细节。