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生成离线文档，便于分享。

参考来源：