在 Spring Boot 中自定义 Swagger URL
1、概览
Springfox 和 SpringDoc 这两个工具简化了 Swagger API 文档的生成和维护。
在本教程中,我们将了解如何在 Spring Boot 应用中更改 Swagger-UI URL 前缀。
2、使用 Springdoc 时更改 Swagger UI URL 前缀
首先,我们可以看看 如何使用 OpenAPI 3.0 生成 REST API 文档。
根据上述教程,我们需要添加如下 SpringDoc 的依赖:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.0.2</version>
</dependency>
swagger-ui 的默认 URL 是 http://localhost:8080/swagger-ui.html
。
比方说,我们要增加 /myproject
前缀,接下来让我们看看自定义 swagger-UI URL 的两种方法。
2.1、application.properties
我们可以在 application.properties
文件中添加以下属性来修改 swagger-UI URL:
springdoc.swagger-ui.disable-swagger-default-url=true
springdoc.swagger-ui.path=/myproject
2.2、配置类
我们也可以通过配置类来实现:
@Component
public class SwaggerConfiguration implements ApplicationListener<ApplicationPreparedEvent> {
@Override
public void onApplicationEvent(final ApplicationPreparedEvent event) {
ConfigurableEnvironment environment = event.getApplicationContext().getEnvironment();
Properties props = new Properties();
props.put("springdoc.swagger-ui.path", swaggerPath());
environment.getPropertySources()
.addFirst(new PropertiesPropertySource("programmatically", props));
}
private String swaggerPath() {
return "/myproject"; // TODO 你可以实现自定义的逻辑
}
}
在这种情况下,我们需要在应用启动前注册监听器:
public static void main(String[] args) {
SpringApplication application = new SpringApplication(SampleApplication.class);
application.addListeners(new SwaggerConfiguration());
application.run(args);
}
3、使用 Springfox 时更改 Swagger UI URL 前缀
我们可以通过《设置 Swagger 文档示例和描述》 和 《使用 Springfox 通过 Spring REST API 设置 Swagger 2》 来了解如何生成 REST API 文档。
首先,根据上述教程,我们需要添加如下的 Springfox 依赖:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
比方说,我们想将此 URL 更改为 http://localhost:8080/myproject/swagger-ui/index.html
。
3.1、pplication.properties
与上述 SpringDoc 的示例类似,在 application.properties
文件中添加以下属性即可:
springfox.documentation.swagger-ui.base-url=myproject
3.2、在配置类种使用 Docket Bean
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
@Override
public void addViewControllers(ViewControllerRegistry registry) {
registry.addRedirectViewController("/myproject", "/");
}
4、添加一个重定向 Controller
我们还可以添加一个专门用于重定向的 API 端点。在这种情况下,不论你使用的是 SpringDoc 还是 Springfox 都可以:
@Controller
public class SwaggerController {
@RequestMapping("/myproject")
public String getRedirectUrl() {
return "redirect:swagger-ui.html";
}
}
5、总结
在本文中,我们学习了如何在 Spring Boot 应用中更改 REST API 文档的默认 swagger-ui URL,不论使用的是 Springfox 还是 SpringDoc。
参考:https://www.baeldung.com/spring-boot-custom-swagger-url