111

snailmall-user-service/src/main/java/com/njupt/swg/swagger/SwaggerConfig.java

@@ -14,29 +14,55 @@ import springfox.documentation.spring.web.plugins.Docket;
  * @CONTACT 317758022@qq.com
  * @DESC
  */
+// @Configuration 注解用于标识这个类是一个配置类，在 Spring 框架中，配置类可以替代传统的 XML 配置文件，
+// 用于定义各种 Bean、配置属性以及进行一些框架相关的初始化设置等操作，Spring 容器在启动时会自动扫描并处理带有该注解的类，
+// 将其中定义的 Bean 注册到容器中，方便在其他地方通过依赖注入等方式使用这些 Bean。
 @Configuration
 public class SwaggerConfig {
-    // 接口版本号
+    // 定义接口版本号，这里指定为 "3.0"，用于在 Swagger 生成的 API 文档中清晰地展示当前接口所遵循的版本，方便使用者了解 API 的迭代情况以及兼容性等信息。
     private final String version = "3.0";
-    // 接口大标题
+    // 接口大标题，设置为 "快乐蜗牛商城V3.0文档"，它会显示在 Swagger 生成的 API 文档页面的显著位置，
+    // 让查看文档的人一眼就能知晓该文档对应的项目名称及大致版本情况，对整体的 API 服务有一个直观的认识。
     private final String title = "快乐蜗牛商城V3.0文档";
-    // 具体的描述
+    // 具体的描述信息，这里描述为 "用户服务"，用于更详细地说明该 API 文档所涵盖的服务范围，
+    // 让使用者清楚这些接口主要是围绕用户相关的功能进行提供的，比如用户的注册、登录、信息查询与修改等操作对应的接口说明都包含在此文档中。
     private final String description = "用户服务";
-    // 服务说明url
+    // 服务说明的 URL，指向 "http://www.kingeid.com"，这个 URL 可以是项目的官方网站、详细的服务条款页面或者其他与该服务相关的介绍页面，
+    // 在 Swagger 文档中点击对应的链接，使用者可以跳转到该页面进一步了解服务的详细规则、使用限制等相关信息。
     private final String termsOfServiceUrl = "http://www.kingeid.com";
-    // 接口作者联系方式
+    // 接口作者的联系方式相关信息，通过创建一个 Contact 类的实例来表示，这里指定了作者的名称为 "fourColor"，
+    // 代码仓库的链接为 "https://github.com/sunweiguo"，以及邮箱地址为 "sunweiguode@gmail.com"，方便使用者在有问题或者建议时能够联系到接口的作者，
+    // 提高沟通效率，同时也体现了接口的可维护性和对使用者的友好性。
     private final Contact contact = new Contact("fourColor", "https://github.com/sunweiguo", "sunweiguode@gmail.com");
 
+    /**
+     * @Bean 注解用于标识这个方法会返回一个 Bean 对象，该对象会被 Spring 容器管理并注册到容器中，
+     * 在其他地方（比如其他类中需要使用这个 Docket 对象时）可以通过依赖注入的方式获取并使用它。
+     * 这个方法主要用于构建一个 Docket 对象，Docket 是 Swagger 中用于配置 API 文档相关信息以及扫描哪些接口来生成文档的核心类。
+     * 在这里它配置了 Swagger 使用的文档类型为 SWAGGER_2（当前常用的一种 Swagger 文档规范版本），
+     * 并通过调用 buildApiInf() 方法来设置 API 的详细信息（如标题、版本、描述、作者联系方式等），最后通过 select() 方法进行接口的选择配置（虽然这里还没有具体配置选择规则，只是简单调用了 build 方法），
+     * 以此来生成一个完整的 Docket 对象，用于后续 Swagger 生成符合要求的 API 文档。
+     *
+     * @return 返回一个配置好的 Docket 对象，该对象承载了 Swagger 生成 API 文档所需要的各项配置信息，
+     *         包括文档类型、API 基本信息以及接口选择规则等，是 Swagger 与 Spring 集成并生成文档的关键配置对象。
+     */
     @Bean
     public Docket buildDocket() {
         return new Docket(DocumentationType.SWAGGER_2).apiInfo(buildApiInf())
                 .select().build();
     }
 
+    /**
+     * 这个私有方法用于构建一个 ApiInfo 对象，ApiInfo 类用于封装 API 的详细信息，
+     * 如前面定义的标题（title）、服务条款 URL（termsOfServiceUrl）、描述（description）、版本（version）以及作者联系方式（contact）等信息，
+     * 通过调用 ApiInfoBuilder 类的一系列方法（链式调用），将这些信息依次设置到 ApiInfo 对象中，最后通过 build() 方法构建出一个完整的 ApiInfo 对象返回，
+     * 这个对象会被 buildDocket() 方法获取并设置到 Docket 对象中，用于在 Swagger 生成的 API 文档中展示这些详细的 API 相关信息，让使用者全面了解 API 的情况。
+     *
+     * @return 返回一个构建好的 ApiInfo 对象，其中包含了 API 的各种基本信息，用于在 Swagger 文档中展示接口的相关描述、版本、作者等详情，方便使用者查看和使用 API。
+     */
     private ApiInfo buildApiInf() {
         return new ApiInfoBuilder().title(title).termsOfServiceUrl(termsOfServiceUrl).description(description)
                 .version(version).contact(contact).build();
 
     }
-
 }