Ubuntu-Swagger自定义配置方法详解

Ubuntu系统下Swagger的个性化配置方案详解，本文将从两种主流实现方式入手，帮助开发者快速掌握定制技巧。

一 前置准备

1. 在Ubuntu系统中，Swagger/OpenAPI的自定义配置主要分为两种实现路径：基于Node.js+Express框架托管Swagger UI，或通过Spring Boot项目内嵌Swagger2/Swagger UI组件。
2. 选择Node.js方案时，需先完成运行环境搭建：
   1. 执行命令安装基础环境：sudo apt update && sudo apt install -y nodejs npm
   2. 安装必要的npm包：npm i -D swagger-ui-express yamljs
3. 若采用Spring Boot方案，只需在项目pom.xml中添加springfox-swagger2与springfox-swagger-ui依赖即可完成基础配置。

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

1. 规范文件准备：创建swagger.yaml格式的API文档：
   1. 定义基础信息：swagger: '2.0'
   2. 配置API元数据：
      1. title: Sample API
      2. description: A sample API
      3. version: 1.0.0
   3. 设置接口路径：
      1. /users:
         1. get:
            1. summary: List all users
            2. responses:
               1. '200':
                  1. description: An array of users
2. 集成Swagger UI服务：
   1. 创建app.js文件并添加以下代码：
      1. const express = require('express');
      2. const swaggerUi = require('swagger-ui-express');
      3. const YAML = require('yamljs');
      4. const swaggerDocument = YAML.load('./swagger.yaml');
      5. const app = express();
      6. app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {deepLinking: true,presets: [swaggerUi.presets.apis, swaggerUi.presets.promises],plugins: [swaggerUi.plugins.DownloadUrl],layout: 'StandaloneLayout'}));
      7. const port = process.env.PORT || 3000;
      8. app.listen(port, () => console.log(Server running at http://localhost:${port}/api-docs));
3. 启动服务后通过http://localhost:3000/api-docs访问文档

常用UI配置参数说明：deepLinking：支持直接定位到特定接口presets/plugins：加载预设功能模块layout：设置页面布局样式

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

1. 添加Maven依赖：
   1. io.springfox:springfox-swagger2:2.9.2
   2. io.springfox:springfox-swagger-ui:2.9.2
2. 创建配置类SwaggerConfig.java：
   1. @Configuration
   2. @EnableSwagger2
   3. public class SwaggerConfig {
      1. @Value("${swagger.enabled:true}")
      2. private boolean enabled;
      3. @Bean
      4. public Docket createRestApi() {
         1. return new Docket(DocumentationType.SWAGGER_2)
            1. .enable(enabled)
            2. .apiInfo(apiInfo())
            3. .select()
            4. .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            5. .paths(PathSelectors.any())
            6. .build()
            7. .securitySchemes(securitySchemes()).securityContexts(securityContexts());
      5. }
      6. private ApiInfo apiInfo() { … }
      7. private List securitySchemes() { … }
      8. private List securityContexts() { … }
      9. }
3. 核心配置要点：
   1. 通过Docket配置接口扫描范围
   2. 使用paths方法进行路径过滤
   3. 集成安全认证机制
   4. 支持动态启用/禁用文档

四 部署与运维建议

1. Docker快速部署方案：
   1. 获取官方镜像：docker pull swaggerapi/swagger-ui-express
   2. 启动容器服务：docker run -p 8080:8080 swaggerapi/swagger-ui-express
   3. 访问http://localhost:8080查看效果
2. 生产环境注意事项：
   1. 建议仅在测试环境开放文档
   2. 规范文件需纳入版本管理
   3. 避免暴露敏感实现细节

通过上述两种配置方案，开发者可以灵活实现Swagger文档的个性化定制，建议根据项目实际需求选择最适合的技术路线。