1. 概述
作为优秀的开发者，我们知道在构建REST API时，文档是至关重要的，因为它帮助API消费者无缝工作。如今，大多数Java开发者都在使用 Spring Boot。目前，有两个工具简化了使用 Swagger API文档的生成和维护：Springfox 和 SpringDoc。
在这篇教程中，我们将了解如何更改由这些工具提供的Swagger-UI的URL前缀。
2. 使用SpringDoc更改Swagger UI URL前缀
首先，我们可以参考如何使用OpenAPI 3.0设置REST API文档。
按照上述教程，我们需要添加一个依赖项：
<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。
让我们来看看两种方法来定制Swagger-UI的URL，比如最初设置为/myproject。
2.1. 使用application.properties文件
由于我们已经熟悉Spring中的各种属性，我们需要在application.properties文件中添加以下属性：
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: implement your logic here.
}
}
在这种情况下，我们需要在应用启动之前注册监听器：
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为示例和描述设置Spring REST API和使用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. 使用application.properties文件
与SpringDoc的上述示例类似，在application.properties文件中添加以下属性，将成功更改URL。
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. 添加重定向控制器
我们还可以在API端点上添加重定向逻辑。在这种情况下，无论使用SpringDoc还是Springfox，这都不会有影响：
@Controller
public class SwaggerController {
@RequestMapping("/myproject")
public String getRedirectUrl() {
return "redirect:swagger-ui/";
}
}
5. 总结
在这篇文章中，我们学习了如何使用Springfox和SpringDoc更改REST API文档的默认Swagger-UI URL。
如往常一样，本文的完整代码示例可以在Springfox版本的GitHub仓库中找到这里，而SpringDoc版本的示例可以在这里找到。