springdoc swagger-ui HTML页面如何配置自定义URL？

Question

将 springdoc-openapi-ui 依赖项添加到我的 Spring 项目（不是 Spring Boot）后生成 OpenAPI V3 文档，可以使用默认的 swagger-ui 页面查看：localhost:8080/swagger-ui.html。因为 springdoc 文档替换了以前的 Swagger 文档，所以我想在同一 URL localhost:8080/docs/index.html 上提供它。根据 springdoc 文档，我得到的印象可以通过使用 application.properties 中的 springdoc.swagger-ui.path 选项来完成：

springdoc.swagger-ui.path=/docs/index.html

但是，我希望能够通过转到 localhost:8080/docs/index.html 导航到 API 文档，但我得到了 404，localhost:8080/swagger-ui.html 仍然有效，但现在重定向到 http://localhost:8080/docs/swagger-ui/index.html?configUrl=/restapi/v3/api-docs/swagger-config。

如何配置我的项目也使 swagger-ui 页面通过自定义 URL 可用，即 localhost:8080/docs/index.html 而不是默认的 localhost:8080/swagger-ui.html？

编辑

在尝试更多使其正常工作并查看在线可用信息后，例如 springdoc FAQ（在 this H3AR7B3A7 的回答中提到）我无法让它工作。我决定采用不同的解决方案，它应该具有相同的效果。 springdoc.swagger-ui.path 选项允许指定自定义 URL，但据我了解，转到自定义 URL 会将用户重定向到标准 localhost:8080/swagger-ui.html 页面。所以现在手动配置重定向：

@RequestMapping("/docs/index.html")
public void apiDocumentation(HttpServletResponse response) throws IOException {
  response.sendRedirect("/swagger-ui.html");
}

Answer 1

我通过清晰的代码解决了。 问题出在 webflux 中，对于某些 uri 资源，安全性需要 permitAll，所以我在 WebFlux Security 中以这种模式解决了我在 Springboot 中没有 WebFlux 的图像：

                .authorizeExchange().pathMatchers(
// START To show swagger 3:
                        "/swagger-ui.html",
                        "/webjars/swagger-ui/**",
                        "/v3/api-docs/swagger-config",
                        "/v3/api-docs", // This is the one URI resource used by openApi3 too.
// END To show swagger 3:
                        "/other-uri-permitAll",
                        ...
                        "/other-uri-permitAll_N",
                   .permitAll()
                .and()
                .authorizeExchange().pathMatchers(
                        "/other-uri-authenticated-only_1",
                        "...",
                        "/other-uri-authenticated-only_1")
                    .authenticated()
                .and()
                .authenticationManager(myAuthenticationManager)
                .securityContextRepository(mySecurityContextRepository)
                .authorizeExchange().anyExchange().authenticated()
                .and()
                .build();

Answer 2

Spring Boot 2.5.6 和 springdoc-openapi-webflux-ui 1.5.12 有类似的任务。我为自己找到了几种可能的解决方案。也许它会对其他人有所帮助。

---

直接设置springdoc.swagger-ui.path

直接的方法是设置属性springdoc.swagger-ui.path=/custom/path。如果您可以在应用程序中硬编码swagger 路径，它将完美运行。

---

覆盖springdoc.swagger-ui.path 属性

您可以使用ApplicationListener<ApplicationPreparedEvent> 以编程方式更改默认swagger-ui 路径。这个想法很简单 - 在 Spring Boot 应用程序启动之前覆盖 springdoc.swagger-ui.path=/custom/path。

@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 "/swagger/path"; //todo: implement your logic here.
    }
}

在这种情况下，您必须在应用程序启动之前注册监听器：

@SpringBootApplication
@OpenAPIDefinition(info = @Info(title = "APIs", version = "0.0.1", description = "APIs v0.0.1"))
public class App {
    public static void main(String[] args) {
        SpringApplication application = new SpringApplication(App.class);
        application.addListeners(new SwaggerConfiguration());
        application.run(args);
    }
}

---

使用控制器重定向

您还可以注册自己的控制器并进行简单的重定向（与您的建议相同，但在我的情况下，我需要使用WebFlux 方法）：

@RestController
公共类 SwaggerEndpoint {

    @GetMapping("/自定义/路径")
    公共 Mono api(ServerHttpResponse 响应) {
        response.setStatusCode(HttpStatus.PERMANENT_REDIRECT);
        response.getHeaders().setLocation(URI.create("/swagger-ui.html"));
        返回 response.setComplete();
    }
}

这种方法的问题 - 如果您通过地址 "/swagger-ui.html" 调用它，您的服务器仍然会响应。

Answer 3

显然，该库仅与您在评论中提到的 spring-boot 应用程序本地集成。 如果你想使用 spring，这是可能的，但没有记录集成细节，因为它实际上取决于版本/模块和你 spring 应用程序的性质。

您可以查看FAQ，看看它是否回答了您的问题。

还有一些答案here on SO。