Swagger2配置方式(解决404报错)

Swagger2是一种用于RESTful服务的开源框架，可以帮助我们实现API文档的生成、测试、调试等任务。但在使用过程中，我们可能会遇到“404 Not Found”报错。本文将详细讲解Swagger2的配置方式，以解决此类报错问题。

1. 导入Swagger2依赖

在我们的Spring Boot项目中，需要在pom.xml中添加Swagger2的依赖，如下所示：

<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>

2. 配置Swagger2

在配置Swagger2之前，我们需要创建一个Swagger2配置类，用于初始化Swagger2的相关配置。具体代码如下：

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

    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("API接口文档")
                .version("1.0")
                .build();
    }
}

代码中的createRestApi方法用于创建一个Docket对象，核心就是使用select()函数生成的各种API配置。其中apis(RequestHandlerSelectors.basePackage("com.example.controller"))表示扫描该包下的所有Controller，并生成API文档。paths(PathSelectors.any())表示所有的API接口都会被生成文档。

getApiInfo方法用于实例化API文档信息对象ApiInfo。该对象包括了文档的标题、描述和版本等基本信息。

3. 在Controller中添加@Api注解

为了让Swagger2能够自动扫描到我们的API接口，我们需要在所有的Controller中添加@Api注解，如下所示：

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {
    @ApiOperation("添加用户")
    @PostMapping("/add")
    public void addUser(@RequestBody User user) {
        // 添加用户代码
    }

    @ApiOperation("删除用户")
    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) {
        // 删除用户代码
    }

    @ApiOperation("更新用户")
    @PutMapping("/{id}")
    public void updateUser(@PathVariable Long id, @RequestBody User user) {
        // 更新用户代码
    }

    @ApiOperation("查询用户")
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // 查询用户代码
    }
}

代码中的@Api注解用于指定该Controller的标签，方便在Swagger2中显示。@ApiOperation注解用于指定该方法的API文档信息。

4. 运行项目并访问Swagger2页面

最后，我们需要运行项目，访问Swagger2的页面，查看是否能够正常访问API文档。

在浏览器中访问：http://localhost:8080/swagger-ui.html

如果成功访问Swagger2页面，则表示配置成功。

示例1：解决冲突

如果我们在pom.xml中同时引入了Swagger2和Springfox-swagger-ui，可能会发生冲突，导致404报错。在这种情况下，我们需要移除其中一个依赖。

<!-- 移除Springfox-swagger-ui依赖 -->
<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-ui依赖 -->
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.5.9</version>
  <exclusions>
    <exclusion>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-core</artifactId>
    </exclusion>
  </exclusions>
</dependency>
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-core</artifactId>
  <version>1.5.9</version>
</dependency>

示例2：配置JWT认证

如果我们的API需要使用JWT认证，我们需要在Swagger2配置类中添加相应的配置，如下所示：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(Collections.singletonList(apiKey())) // 添加JWT认证
                .securityContexts(Collections.singletonList(securityContext())); // 添加JWT认证
    }

    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("API接口文档")
                .version("1.0")
                .build();
    }

    // 添加JWT认证
    private ApiKey apiKey() {
        return new ApiKey("JWT", HttpHeaders.AUTHORIZATION, In.HEADER.name());
    }

    // 添加JWT认证
    private SecurityContext securityContext() {
        return SecurityContext.builder()
                .securityReferences(Collections.singletonList(new SecurityReference("JWT", new AuthorizationScope[]{})))
                .build();
    }
}

代码中的securitySchemes函数用于添加JWT认证，securityContexts函数用于配置JWT的安全上下文。

结束语

通过以上步骤，我们就可以完善的配置Swagger2，解决404报错问题，并且支持JWT认证等功能。在实际开发中，根据需要添加、修改配置即可。