SpringBoot 3 轻松集成 SpringDoc swagger-ui 文档解决404问题

后端

2023-01-01 00:37:22

使用 SpringDoc 在 SpringBoot 3 中轻松集成 Swagger 文档

简介

Swagger：API 文档生成神器

Swagger 是一款功能强大的 API 文档生成工具，可帮助开发人员轻松创建交互式的 RESTful API 文档。这些文档对于理解和使用 API 至关重要，可以显著提升开发人员和最终用户的体验。

SpringDoc：Spring Boot 的 Swagger 集成利器

SpringDoc 是一个专为 Spring Boot 设计的 Starter，可帮助您快速、无缝地将 Swagger 集成到您的项目中。借助 SpringDoc，您只需几行代码即可生成全面、交互式的 API 文档。

解决访问 swagger-ui.html 报 404 的难题

在 SpringBoot 3 中，SpringDoc 的默认 UI 路径已从 /swagger-ui.html 更改为 /swagger-ui/index.html。因此，如果您访问 /swagger-ui.html，则会收到 404 错误。

要解决此问题，请将 SpringDoc 的依赖项升级到 2.1.0 或更高版本，并在您的 Spring Boot 项目中添加以下配置：

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

常见问题解答

问题 1：无法生成 Swagger 文档？

答案： 确保您已在代码中添加适当的注释，例如 @ApiOperation、@ApiParam 和 @ApiResponse。这些注释将指导 SpringDoc 生成更详细、更准确的文档。

问题 2：OpenAPI 文档显示错误？

答案： 检查您的代码是否有错误或遗漏，并确保 API 定义与文档中的内容一致。

问题 3：如何自定义 Swagger UI 的外观？

答案： 您可以通过修改 swagger-ui.html 文件来自定义 Swagger UI 的外观。您还可以通过实现 SwaggerUiCustomizer 接口来更精细地控制 UI。

问题 4：如何从外部文档加载 Swagger 定义？

答案： SpringDoc 支持从外部文档（例如 OpenAPI 规范文件）加载 Swagger 定义。您可以在 application.properties 中使用 springdoc.swagger-ui.urls 属性来指定外部文档的 URL。

问题 5：SpringDoc 的优点是什么？

答案： SpringDoc 的优点包括：