Ubuntu Swagger如何进行扩展开发

在Ubuntu上进行Swagger扩展开发，主要基于OpenAPI规范和Spring生态工具，以下是关键步骤：

1. 基础环境准备

   • 安装Node.js、npm和Java（用于运行Swagger工具）：

     sudo apt update sudo apt install nodejs npm openjdk-11-jdk 

   • 全局安装Swagger相关npm包：

     sudo npm install -g swagger-jsdoc swagger-ui-express 

2. 定义API规范

   • 手动创建swagger.json或swagger.yaml文件，或通过Swagger Editor编辑。
   • 示例内容（JSON格式）：

     { "swagger": "2.0", "info": { "title": "API文档", "version": "1.0" }, "paths": { "/api/hello": { "get": { "summary": "示例接口", "responses": { "200": { "description": "成功" } } } } } } 

3. 集成到Spring Boot项目

   • 添加依赖（Maven）：

     <!-- Swagger 2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <!-- 或 Swagger 3（OpenAPI 3.0） --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.8.5</version> </dependency> 

   • 配置类（以Swagger 2为例）：

     @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket api() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .paths(PathSelectors.any()) .build(); } } 

4. 高级扩展开发

   • 自定义插件：通过实现ParameterBuilderPlugin、ApiListingScannerPlugin等接口扩展参数解析、接口扫描逻辑。
     • 示例：添加自定义请求头参数

       @Component public class CustomHeaderPlugin implements ParameterBuilderPlugin { @Override public void apply(ParameterContext context) { context.parameterBuilder() .name("X-Custom-Header") .description("自定义请求头") .required(true) .parameterType("header"); } @Override public boolean supports(DocumentationType delimiter) { return true; } } 

   • 聚合多模块文档：通过SwaggerResourcesProvider合并不同模块的OpenAPI规范。
   • 动态文档生成：结合Spring AOP或拦截器，在运行时动态修改接口描述。

5. 测试与部署

   • 启动Spring Boot应用，访问Swagger UI：
     • Swagger 2：http://localhost:8080/swagger-ui.html
     • Swagger 3：http://localhost:8080/swagger-ui/index.html
   • 使用swagger-maven-plugin生成离线文档，便于分享。

参考来源：