在 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