Update Swagger2Config.java

src/main/java/com/zsz/config/Swagger2Config.java

@@ -20,68 +20,87 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * Swagger2配置信息
+ * Swagger2 接口文档配置类
+ * 功能：配置Swagger2生成RESTful API文档
+ * 包含：接口分组、全局参数、接口过滤等配置
  */
-@Configuration
-@EnableSwagger2
+@Configuration  // 声明为Spring配置类
+@EnableSwagger2  // 启用Swagger2功能
 public class Swagger2Config {
 
+    /**
+     * 配置Web接口文档分组
+     * 包含：全局header参数、接口扫描范围等配置
+     * @return Docket对象
+     */
     @Bean
     public Docket webApiConfig(){
-
-        //添加head参数start
+        // ==================== 配置全局header参数 start ====================
         List<Parameter> pars = new ArrayList<>();
+        
+        // 用户ID参数配置
         ParameterBuilder tokenPar = new ParameterBuilder();
-        tokenPar.name("userId")
-                .description("用户ID")
-                .defaultValue("1")
-                .modelRef(new ModelRef("string"))
-                .parameterType("header")
-                .required(false)
+        tokenPar
+.name("userId")               // 参数名称
+                .description("用户ID")        // 参数描述
+                .defaultValue("1")            // 默认值
+                .modelRef(new ModelRef("string"))  // 参数类型
+                .parameterType("header")       // 参数位置（header）
+                .required(false)               // 是否必填
                 .build();
-        pars.add(tokenPar.build());
+        pars
+.add(tokenPar.build());  // 添加到参数列表
 
+        // 临时用户ID参数配置
         ParameterBuilder tmpPar = new ParameterBuilder();
-        tmpPar.name("userTempId")
-                .description("临时用户ID")
-                .defaultValue("1")
-                .modelRef(new ModelRef("string"))
-                .parameterType("header")
-                .required(false)
+        tmpPar
+.name("userTempId")             // 参数名称
+                .description("临时用户ID")   // 参数描述
+                .defaultValue("1")            // 默认值
+                .modelRef(new ModelRef("string"))  // 参数类型
+                .parameterType("header")      // 参数位置
+                .required(false)             // 是否必填
                 .build();
-        pars.add(tmpPar.build());
-        //添加head参数end
+        pars
+.add(tmpPar.build());  // 添加到参数列表
+        // ==================== 配置全局header参数 end ====================
 
-        return new Docket(DocumentationType.SWAGGER_2)
-                .groupName("webApi")
-                .apiInfo(webApiInfo())
+        return new Docket(DocumentationType.SWAGGER_2)  // 指定Swagger2版本
+                .groupName("webApi")                   // 分组名称
+                .apiInfo(webApiInfo())                 // 设置文档信息
                 .select()
-                //可以测试请求头中：输入token
-                //.apis(RequestHandlerSelectors.withClassAnnotation(ApiOperation.class))
-                .apis(RequestHandlerSelectors.basePackage("com.zsz.controller"))
-                //过滤掉admin路径下的所有页面
-                //.paths(Predicates.and(PathSelectors.regex("/sms/.*")))
-                //过滤掉所有error或error.*页面
-                //.paths(Predicates.not(PathSelectors.regex("/error.*")))
+                // 指定扫描的Controller包路径
+                .apis(RequestHandlerSelectors.basePackage("com.zsz.controller"))  
+                // 可选过滤配置（当前注释状态）：
+                // 1. 只扫描带@ApiOperation注解的方法
+                // .apis(RequestHandlerSelectors.withClassAnnotation(ApiOperation.class))
+                // 2. 过滤指定路径
+                // .paths(Predicates.and(PathSelectors.regex("/sms/.*")))
+                // 3. 排除错误路径
+                // .paths(Predicates.not(PathSelectors.regex("/error.*")))
                 .build()
-                .globalOperationParameters(pars);
-
+                .globalOperationParameters(pars);  // 添加全局参数
     }
 
-
-
+    /**
+     * 配置Web接口文档信息
+     * @return 文档信息对象
+     */
     private ApiInfo webApiInfo(){
-
         return new ApiInfoBuilder()
-                .title("网站-API文档")
-                .description("本文档描述了网站微服务接口定义")
-                .version("1.0")
-                .contact(new Contact("atguigu", "http://atguigu.com", "512111559@qq.com"))
+                .title("网站-API文档")         // 文档标题
+                .description("本文档描述了网站微服务接口定义")  // 文档描述
+                .version("1.0")               // 版本号
+                .contact(new Contact("atguigu", "http://atguigu.com", "512111559@qq.com"))  // 联系人信息
                 .build();
     }
 
+    /**
+     * 配置后台管理接口文档信息
+     * （备用方法，当前未使用）
+     * @return 文档信息对象
+     */
     private ApiInfo adminApiInfo(){
-
         return new ApiInfoBuilder()
                 .title("后台管理系统-API文档")
                 .description("本文档描述了后台管理系统微服务接口定义")
@@ -89,6 +108,4 @@ public class Swagger2Config {
                 .contact(new Contact("atguigu", "http://atguigu.com", "512111559@qq.com"))
                 .build();
     }
-
-
-}
+}