springfox 2.2.2 没有生成 api-docs

Posted 2023-02-27

【中文标题】springfox 2.2.2 没有生成 api-docs

【英文标题】：springfox 2.2.2 no api-docs generated

【发布时间】：2016-02-20 04:46:57

【问题描述】：

我正在努力将 Springfox 2.2.2 集成到我的 Spring MVC 项目中，但没有像我想的那样生成 api-docs。下面是一些关于我的配置的信息。

我提供了以下依赖项（连同其他库，如 fastxml、webjar、使用正确版本的 spring 等）

    <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.2.2</version>
</dependency>

Springfox配置如下：

    package com.exemplarypackage.config;
@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan("com.exemplarypackage.controller")
public class SwaggerConfig extends WebMvcConfigurerAdapter
    @Bean
    public Docket api()
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    

    private ApiInfo apiInfo() 
        ApiInfo apiInfo = new ApiInfo(
                "My Project's REST API", 
                "This is a description of your API.", 
                "API TOS",
                "url",
                "[e-mail]", 
                "API License", 
                "API License URL");
        return apiInfo;
    

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) 
        registry
            .addResourceHandler("swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");
        registry
            .addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
    

    

示例控制器如下所示：

package com.exemplarypackage.controller;
@Api(value = "test class for springfox")
@Controller
public class TestController 
    @ApiOperation(value = "Returns test details")
    @ApiResponses(value = 
        @ApiResponse(code = 200, message = "Successful retrieval", response = Test.class),
        @ApiResponse(code = 404, message = "Test does not exist"),
        @ApiResponse(code = 500, message = "Internal server error")
    )
    @RequestMapping(value = "/test", method = RequestMethod.GET)
    public String test(Locale locale, Model model) 
        logger.info("TEST");
        return "test";
    

通过上述设置，当我执行 url: localserver:8080/myApp/swagger-ui 时几乎没有任何显示但没有错误消息。

然后，我将在 spring-fox-swagger-ui-2.2.2.jar 中找到的内容添加到 src/main/resources/META-INF（我将其解压缩并粘贴到给定文件夹）。现在，当我转到 localserver:8080/myApp/swagger-ui 时，所有绿色图形都会显示，但没有 api 文档。我在服务器日志中注意到 swagger-ui 会查找 swagger-resources 端点，但它会得到 404。当我浏览服务器日志时，我看到没有创建这样的端点：swagger-resources、v2/api-docs 等。但是，我注意到这些类被过滤为 swagger 注释......有一个 springfox。 META-INF/resources/webjars/springfox-swagger-ui 文件夹中包含 swagger-resorces 端点的 Node.js 文件 - 也许它应该切换到不同的名称？

我不知道如何让它工作......我应该以某种方式声明这些端点还是应该自动创建它们？也许我只是错过了一些小东西，但我最近几天一直在与这个问题作斗争，无法弄清楚应该配置什么才能使其正常工作。

【问题讨论】：

当您导航到localserver:8080/myApp/v2/api-docs 时会得到什么？

你的 servlet 配置是什么样的？

【参考方案1】：

我已经在@zubactick 的帮助下解决了这个问题。 目前，我对 springfox 和 mvc 有单独的配置类。所以，我的 springfox 配置是这样的：

package com.myPackage.config;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig


    @Bean
    public Docket api()
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .groupName("test")
                .apiInfo(apiInfo());
    

    private ApiInfo apiInfo() 
        ApiInfo apiInfo = new ApiInfo(
                "My Project's REST API", 
                "This is a description of your API.", 
                "API TOS",
                "url",
                "[e-mail]", 
                "API License", 
                "API License URL");
        return apiInfo;
    

我的 MVC 配置是这样的：

package com.myPackage.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.web.servlet.ViewResolver;
import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import org.springframework.web.servlet.view.InternalResourceViewResolver;

@Configuration
@EnableWebMvc
@Import(SwaggerConfig.class)
@ComponentScan("com.myPackage.controller")
public class WebSpringConfig extends WebMvcConfigurerAdapter

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) 
        registry.addResourceHandler("/resources/**").addResourceLocations("/resources/");
        registry
            .addResourceHandler("swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");
        registry
            .addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
    

    @Bean
    public ViewResolver configureViewResolver() 
        InternalResourceViewResolver viewResolve = new InternalResourceViewResolver();
        viewResolve.setPrefix("/WEB-INF/views/");
        viewResolve.setSuffix(".jsp");

        return viewResolve;
    

    @Override
    public void configureDefaultServletHandling(
            DefaultServletHandlerConfigurer configurer) 
        configurer.enable();
    

   

此外，web.xml 文件中指定了以下内容：

<servlet>
        <servlet-name>appServlet</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
        <param-name>contextClass</param-name>
        <param-value>org.springframework.web.context.support.AnnotationConfigWebApplicationContext</param-value>
        </init-param>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>com.myPackage.config.WebSpringConfig</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

控制器可以与问题中提供的相同，但是使用上面的 swagger 配置，我声明的包中的所有控制器都由 swagger 扫描和记录。

【讨论】：

谢谢，这只是帮助我弄清楚了使用@Import（SwaggerConfig.class）作为@ComponentScan（“com.myPackage.controller”，“com.myPackage.config ") 或 @SpringBootApplication(scanBasePackages="com.myPackage.config") 不适用于 springfox。

【参考方案2】：

@gromajus，您能否尝试在您的示例控制器类中使用@RestController 注释而不是@Controller 注释？

【讨论】：

它没有帮助 - 我将 @Controller 更改为 @RestController 但没有任何改变：/

@gromajus，我也看到您尝试获取swagger-ui 而不是swagger-ui.html，但正如@Dilip Krishnan 提到的，您应该在api-docs 端点上获取一些json。您的应用程序是否在没有任何警告的情况下构建并在没有警告和错误的情况下部署？

@gromajus，我最近在使用 springfox 时遇到了同样的问题。我不是一个经验丰富的直觉。但是除了控制器注释之外，我发现我的配置和您的配置之间存在一些差异。它们是：我有用于 MVC 配置和 Swagger 配置的类，而不是你的示例中的单个配置类，@Configuration 注释我有最后一个，我不使用@Api，因为我在某处（可能在 java doc 中）读到它已被弃用，我在谷歌搜索导入的包时也看到了一些错误。您能否提供您的import 声明（来自 springfox pckg 的@Api）？

我使用 swagger-ui.html :) 没有警告也没有错误。但是也没有可用的 api-docs (v2/api-docs) 端点：/关于我在 Controller 类中的 springfox 导入，它们如下：import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiResponses; import io.swagger.annotations.ApiResponse;

让我担心的是，我在服务器日志中看到实际上有两次映射我的端点。我首先看到：/v2/api-docs、/swagger-resources、/configuration/security、/configuration/ui、/swagger-ui.html、/webjars/**、/resources/**。但是在第二次运行中，只有我在 swagger 配置类中明确声明的最后三个。我想知道为什么要执行第二次运行？另外，你能@zubactik 分享你的配置和控制器类吗？