Swagger自动生成API文档

摘要：当一个类中的方法比较多会通过加上注释以区分，当类也比较多时如何管理呢？本文记录使用Swagger自动生成API文档，将不同类中的接口统一管理。

Swagger API文档是一种用于描述和可视化RESTful API的工具，具有接口文档生成、接口测试、接口可视化、接口协作、代码生成等多种功能。可帮助开发人员更好地理解、测试和使用RESTful API，提高了开发效率和协作能力。

首先，需要在pom.xml文件中引入相关依赖；并在入口启动类中，增加注解@EnableSwagger2，开启Swagger能力。

<!--swagger相关依赖配置-->
<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>

然后，在config目录放置SpringFoxConfig.java配置类文件（模板化代码直接使用），具体说明见注释；完成配置类的coding后还需要增加地址映射类WebMvcConfigurer.java。

SpringFoxConfig.java
/**
 * SpringFoxConfig类是一个实现Swagger2Configurer接口的类，它用于配置Swagger 2。
 * Swagger是一个用于生成API文档的工具，它可以自动生成API的HTML文档，并提供API的交互信息。
 * @Configuration用于标识一个类是一个配置类。配置类是一个用于配置Spring容器中各种Bean的类，
 * 例如视图解析器、拦截器、处理器映射器等
 */
@Configuration
public class SpringFoxConfig {

  // 访问http://localhost:8083/swagger-ui.html可以看到API文档
  // 配置Swagger 2的API文档
  @Bean
  public Docket api() {
      return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo()) //apiInfo()方法来设置API文档的元数据信息, 标题、描述、版本号等。
        .select()  // select()方法，用于指定要生成API文档的API
        .apis(RequestHandlerSelectors.any())//Req...any()表示我们要生成所有Controller层的API
        .paths(PathSelectors.any())   // PathSelectors.any()来表示我们要生成所有路径的API
        .build();  // build()方法，用于构建Docket对象
  }

  private ApiInfo apiInfo() {
      return new ApiInfoBuilder()
        .title("Swagger页面title")
        .description("")
        .termsOfServiceUrl("")
        .build();
  }
}


WebMvcConfigurer.java
/**
 * 描述： 配置地址映射
 * WebMvcConfigurer接口定义了一系列方法，用于配置Spring MVC的属性:如视图解析器、拦截器、处理器
 * 映射器等。
 * 在Spring MVC项目中，我们可以通过实现WebMvcConfigurer接口的类来配置Spring MVC的各种属性。例如，
 * 我们可以实现ViewResolutionConfigurer接口来配置视图解析器，实现InterceptorRegistry接口来配置
 * 拦截器，实现MessageConverter接口来配置消息转换器等。
 */
@Configuration
public class ImoocMallWebMvcConfig implements WebMvcConfigurer {
/**
 * addResourceHandlers(ResourceHandlerRegistry registry)方法是WebMvcConfigurer接口中
 * 定义的一个方法，用于向Spring MVC的资源处理器注册表中添加资源处理器。
 * 资源处理器用于处理静态资源，如CSS、JavaScript、图片等。在Spring Mvc中，可以通过配置资源处理器
 * 来指定静态资源的处理逻辑，例如指定静态资源的路径、指定静态资源的映射URL等。
 * 首先使用addResourceHandler方法添加了一个名为"swagger-ui.html"的资源处理器，并指定了处理路径
 * 为classpath:/META-INF/resources/下的文件。这意味着，当用户请求"swagger-ui.html"文件时，
 * Spring MVC会将其处理为该文件的内容。
 * 接下来，我们使用addResourceHandler方法添加了一个名为"/webjars/"的资源处理器，并指定了处理路径
 * 为classpath:/META-INF/resources/webjars/下的文件。这意味着，当用户请求"/webjars/"路径下
 * 的文件时，Spring MVC会将其处理为该文件的内容。
 * 这样，我们就可以将静态资源（如CSS、JavaScript、图片等）放在classpath:/META-INF/resources/
 * 和classpath:/META-INF/resources/webjars/目录下，并通过"swagger-ui.html"和"/webjars/**"
 * 路径访问它们。
 * @param registry
 */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations(
                "classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations(
                "classpath:/META-INF/resources/webjars/");
    }
}

最后，访问http://<host>:<port>/<context-path>/swagger-ui.html（其中：  <host> 表示服务器的IP地址或域名。 <port> 表示服务器监听的端口号。 <context-path> 表示应用程序的上下文路径。此处为http://localhost:8083/swagger-ui.html）可以看到API文档。配合使用ApiOperation描述API，可以使得生成Swagger文档更加清晰。

// ApiOperation是一个用于描述API操作的注解，它可以包含操作的描述、输入参数、输出参数等信息
// 。在这个示例中，我们定义了一个ApiOperation注解，用于描述一个名为“后台添加目录”的操作。
@ApiOperation("后台添加目录")