如何为 swagger 2.8.0 做友好的基本 url

Question

我正在尝试更改 API 文档的基本访问 url。网址是“http://localhost:8080/swagger-ui.html”。我想要得到类似“http://localhost:8080/myapi/swagger-ui.html”的内容。

我使用 Springfox 2.8.0 Swagger、Java 8、Spring Boot 2.0 swagger的配置是：

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    @Bean
    public Docket api(ServletContext servletContext) {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathProvider(new RelativePathProvider(servletContext) {
                    @Override
                    public String getApplicationBasePath() {
                        return "/myapi";
                    }
                })
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(PathSelectors.regex("/error")))
                .build()
                .useDefaultResponseMessages(false);
    }
}

自定义路径提供程序必须提供帮助，但我仍然可以使用 url“http://localhost:8080/swagger-ui.html”访问 api 文档。如果我使用 url“http://localhost:8080/myapi/swagger-ui.html”，则会收到 404 错误。看下面的截图。

Answer 1

UPD：Springfox 已被放弃

Springfox Swagger 一直是一个有点肮脏的解决方案，有很多不清楚和错误，但到目前为止（2021 年第四季度）它已经一年多没有更新了。

最后一根稻草是 Springfox Swagger 3.0 不再与 Spring Boot 2.6.x 一起使用。

因此，如果您阅读本文，请考虑切换到 https://springdoc.org/。

这是一个非常简单的转换，他们做得很好 记录它。 https://springdoc.org/#migration-from-springfox。

对于那些使用 Springfox Swagger 3.0.0 的人

这里是更改文档基本 URL 的工作配置：

springfox:
  documentation:
    swaggerUi:
      baseUrl: /documentation
    openApi:
      v3:
        path: /documentation/v3/api-docs
    swagger:
      v2:
        path: /documentation/v2/api-docs

Answer 2

您可以像这样编辑您的 SwaggerConfiguration：

小心更换

package

（需要是那个 包含您的 REST 控制器）、您需要的

host

和

PATH

@Configuration
@EnableSwagger2
public class SwaggerConfiguration implements WebMvcConfigurer {

    public static final String PATH = "/myapi";

    @Bean
    public Docket api() {
        final var package = "com.julia.rest";
        final var host = "localhost:8080";

        return new Docket(DocumentationType.SWAGGER_2)
                .host(host)
                .select()
                .apis(RequestHandlerSelectors.basePackage(package))
                .paths(PathSelectors.any())
                .build();
    }

    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        final var apiDocs = "/v2/api-docs";
        final var configUi = "/swagger-resources/configuration/ui";
        final var configSecurity = "/swagger-resources/configuration/security";
        final var resources = "/swagger-resources";

        registry.addRedirectViewController(PATH + apiDocs, apiDocs).setKeepQueryParams(true);
        registry.addRedirectViewController(PATH + resources, resources);
        registry.addRedirectViewController(PATH + configUi, configUi);
        registry.addRedirectViewController(PATH + configSecurity, configSecurity);
        registry.addRedirectViewController(PATH, "/");
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler(PATH + "/**").addResourceLocations("classpath:/META-INF/resources/");
    }
}

另一个解决方案是更改 spring-boot URL context-path:

编辑

application.properties

文件：

server.servlet.context-path=/myapi

或者如果您有

application.yml

文件：

server:
  servlet:
    context-path: /myapi

警告：它将更改所有 Web 服务的基本路径，而不仅仅是 Swagger

Answer 3

我也遇到过这个问题，并尝试了很多可能的解决方案，但没有什么真正有帮助。 就我而言，我无法使用任何资源重定向，因为必须可以通过匹配路径 /api-docs/** 在本地访问 swagger，就像在谷歌云上一样。在谷歌云上，在我的情况下，任何资源重定向都将被拒绝。所有资源也必须从此路径加载

这是我的解决方案：
springfox-swagger2 和 springfox-swagger-ui 版本 2.9.2

@EnableSwagger2
@Configuration
public class SwaggerCommonConfig implements WebMvcConfigurer {
    public static final String PATH = "/api-docs";

    @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(PATH, "/");
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler(PATH + "/**").addResourceLocations("classpath:/META-INF/resources/");
    }
}

并且由于 springfox 没有任何可能性通过其他方式做到这一点，在我的例子中，我们将创建简单的控制器，它将资源请求从我们的自定义路径转换为标准 springfox。 （这不是很优雅的部分，但事实就是这样:)）

@RestController
@RequestMapping(SwaggerGatewayCommonConfig.PATH)
@RequiredArgsConstructor
public class SwaggerController {
    private final RestTemplate restTemplate;
    private final static String V2_API_DOCS = "/v2/api-docs";
    private final static String SWAGGER_RESOURCES_CONFIGURATION_UI = "/swagger-resources/configuration/ui";
    private final static String SWAGGER_RESOURCES_CONFIGURATION_SECURITY = "/swagger-resources/configuration/security";
    private final static String SWAGGER_RESOURCES = "/swagger-resources";
    private final static Pattern pattern = Pattern.compile("http[s]*://([^/]+)", Pattern.CASE_INSENSITIVE);

    @Value("${server.port}")
    private String port;

    @GetMapping(V2_API_DOCS)
    @SuppressWarnings("unchecked")
    public Map<String, Object> getV2ApiDocs(HttpServletRequest request) {
        Matcher matcher = pattern.matcher(request.getRequestURL().toString());
        matcher.find();

        Map<String, Object> resp = (Map<String, Object>) restTemplate.getForObject(toLocalSwaggerUrl(V2_API_DOCS), Map.class);
        //we have to replace standard host, to requested host. as swagger UI make api requests from this host
        resp.put("host", matcher.group(1));

        return resp;
    }

    @GetMapping(SWAGGER_RESOURCES_CONFIGURATION_UI)
    public Object getSwaggerResourcesConfigurationUi() {
        return restTemplate.getForObject(toLocalSwaggerUrl(SWAGGER_RESOURCES_CONFIGURATION_UI), Object.class);
    }

    @GetMapping(SWAGGER_RESOURCES_CONFIGURATION_SECURITY)
    public Object getSwaggerResourcesConfigurationSecurity() {
        return restTemplate.getForObject(toLocalSwaggerUrl(SWAGGER_RESOURCES_CONFIGURATION_SECURITY), Object.class);
    }

    @GetMapping(SWAGGER_RESOURCES)
    public Object getSwaggerResources() {
        return restTemplate.getForObject(toLocalSwaggerUrl(SWAGGER_RESOURCES), Object.class);
    }

    private String toLocalSwaggerUrl(String path) {
        return "http://localhost:" + port + path;
    }
}

我希望它能为也遇到这个问题的人节省时间 =) 祝你好运

Answer 4

Swagger 基本访问 url 是根据您的基本应用程序路径构建的。因此，如果您更改基本应用程序路径，您将获得所需的行为。而且您的所有 api 也将更改为该路径。您可以在此处找到如何更改它如何在 Spring Boot 中设置剩余的基本 url？ .

你所做的只是改变了 swagger 从你的应用程序调用其他 api 的方式，而不是改变他的基本 url。有一些技巧可以在不更改应用程序基本路径的情况下更改 swagger 基本 url（手动移动所有 swagger 资源），但我不建议这样做。

Answer 5

请尝试在 application.properties 中进行设置

##To disable default url swagger-ui/index.html
springdoc.swagger-ui.disable-swagger-default-url=true
##To change base url swagger-ui to myswagger-ui
springdoc.swagger-ui.url=/myswaggerui
##To change /index.html to /restapis
springdoc.swagger-ui.path=/restapis