博客

Springboot下swagger-ui.html访问不到的解决方案

  • Post category:http

下面我会详细讲解“Spring Boot下Swagger UI无法访问”的解决方案。

问题描述

在Spring Boot项目中使用Swagger生成API文档时，会自动生成/swagger-ui.html页面，但在访问该页面时，会出现404错误，无法打开文档页面。

解决方案

方案一：配置资源文件路径

在Spring Boot项目中，静态资源文件默认的路径为/static、/public、/resources、/META-INF/resources，而Swagger UI的相关文件默认在/META-INF/resources/webjars/swagger-ui路径下。

因此，我们需要在项目中配置Swagger UI的资源文件路径，将Swagger UI的资源文件复制到上述任意一个默认的静态资源目录下，或者自定义一个静态资源目录，例如/doc。在应用启动时，将该目录路径添加到静态资源映射中，如下所示：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enabled}")
    private boolean enabled;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(enabled)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger构建RESTful APIs")
                .description("更多Spring Boot相关文章请关注：http://www.xxxx.com/")
                .termsOfServiceUrl("http://www.xxxx.com/")
                .contact("sunf")
                .version("1.0")
                .build();
    }

    /**
     * 配置静态资源目录
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/doc/**").addResourceLocations("classpath:/doc/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

在上面的配置文件中，我们新创建了一个doc目录，在addResourceHandlers方法中将其添加到静态资源映射中。在应用启动后，访问http://localhost:8080/doc/swagger-ui.html即可访问Swagger文档页面。

方案二：自定义Swagger UI页面

除了将静态资源文件复制到某个目录下，我们还可以通过自定义Swagger UI页面来解决访问404的问题。

首先，我们需要从Swagger UI GitHub仓库中下载最新的UI代码。将下载下来的文件复制到自己的项目中，例如/doc目录下。

接下来需要修改/doc/index.html文件中的相关配置，将其与我们的API文档进行绑定。我们可以在该文件中修改Swagger UI的配置信息，例如API文档的标题、描述、请求地址等。

修改完成后，将/doc目录添加到静态资源映射中，如下所示：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enabled}")
    private boolean enabled;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(enabled)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger构建RESTful APIs")
                .description("更多Spring Boot相关文章请关注：http://www.xxxx.com/")
                .termsOfServiceUrl("http://www.xxxx.com/")
                .contact("sunf")
                .version("1.0")
                .build();
    }

    /**
     * 配置静态资源目录
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/doc/**").addResourceLocations("classpath:/doc/");
    }
}

在上面的配置中，我们将/doc目录添加到了静态资源映射中，在应用启动后，访问http://localhost:8080/doc/index.html即可访问自定义的Swagger文档页面。

示例说明

以下代码为一个基于Spring Boot框架的RESTful API应用程序，通过Swagger自动生成API文档。

@RestController
@RequestMapping("/api")
@Api(tags = "用户管理接口")
public class UserController {

    @Autowired
    private UserService userService;

    @ApiOperation(value = "获取用户列表", notes = "获取所有用户列表")
    @RequestMapping(value = "/users", method = RequestMethod.GET)
    public List<User> getUserList() {
        return userService.getUserList();
    }

    @ApiOperation(value = "根据ID获取用户信息", notes = "根据用户ID获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", paramType = "path", required = true, dataType = "String")
    @RequestMapping(value = "/users/{id}", method = RequestMethod.GET)
    public User getUserById(@PathVariable("id") String id) {
        return userService.getUserById(id);
    }

    @ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    })
    @RequestMapping(value = "/users", method = RequestMethod.POST)
    public String addUser(@RequestBody User user) {
        userService.addUser(user);
        return "success";
    }

    @ApiOperation(value = "更新用户信息", notes = "根据User对象更新用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String"),
            @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    })
    @RequestMapping(value = "/users/{id}", method = RequestMethod.PUT)
    public String updateUserById(@PathVariable("id") String id, @RequestBody User user) {
        userService.updateUserById(id, user);
        return "success";
    }

    @ApiOperation(value = "删除用户", notes = "根据ID删除用户")
    @ApiImplicitParam(name = "id", value = "用户ID", paramType = "path", required = true, dataType = "String")
    @RequestMapping(value = "/users/{id}", method = RequestMethod.DELETE)
    public String deleteUserById(@PathVariable("id") String id) {
        userService.deleteUserById(id);
        return "success";
    }

}

在调用接口时，通过/doc/swagger-ui.html或/doc/index.html访问Swagger文档页面，可以方便地查看API文档。

Tags: