如何使用 Swagger2 生成 Spring-boot REST API 文档？答案

【问题标题】：How to generate Spring-boot REST API documentation using Swagger2?如何使用 Swagger2 生成 Spring-boot REST API 文档？
【发布时间】：2016-10-13 09:13:39
【问题描述】：

我正在尝试使用 swagger2 为我的 Spring-boot 应用程序生成 REST API 文档。

这是我的 application.properties 文件内容：

server.port = ${port:8082}
server.contextPath=/myServicePath
spring.h2.console.enabled=true
logging.level.org.hibernate.SQL=debug
spring.datasource.url=jdbc:mysql://${mysql-host:localhost}:${mysql-port:3306}/${mysql-dbname:mydb}
spring.datasource.username=${mysql-user:root}
spring.datasource.password=${mysql-password:password}
spring.datasource.driver-class-name=com.mysql.jdbc.Driver

spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

这是我的 swaggerConfig.Java：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.ApiSelectorBuilder;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.UiConfiguration;
import static springfox.documentation.builders.PathSelectors.*;
@Configuration
public class ApiDocumentationConfiguration {
    @Bean
    public Docket documentation() {
    return new Docket(DocumentationType.SWAGGER_2)
      .select()
        .apis(RequestHandlerSelectors.any())
        //.paths(regex("/.*"))
        .build()
      .pathMapping("/")
      .apiInfo(metadata());
    }
    @Bean
    public UiConfiguration uiConfig() {
      return UiConfiguration.DEFAULT;
    }
    private ApiInfo metadata() {
      return new ApiInfoBuilder()
    .title("My awesome API")
    .description("Some description")
    .version("1.0")
    .contact("my-email@domain.org")
    .build();
    }
}

这里是 Application.Java：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Import;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@ComponentScan
@EnableSwagger2
public class Application {
    public static void main( String[] args ) 
    {
        SpringApplication.run(Application.class, args);
    }
}

这是我的控制器：

@Path("/")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@RestController

public class MyController {

    @Autowired
    private HttpServletRequest request;

    @ApiOperation(value = "doStuff", nickname = "doStuff", response = Response.class)
    @RequestMapping(method = RequestMethod.GET, produces = "application/json")
    public String doStuff(@RequestBody String command) {
        return "TestString";
    }       
}

我正在使用 Spring-boot 1.4.0 和 swagger2。我在 pom.xml 中添加了以下依赖项：

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

当我使用网址http://localhost:8082/swagger-ui.html时，我收到错误 404。

谁能帮我解决这个问题？

提前谢谢你。

【问题讨论】：

你为什么使用@Path？
@CássioMazzochiMolin 我在 application.properties 中定义了 contextPath。
@Path 来自 JAX-RS。我不确定您要使用该注释来实现什么。顺便说一句，您还有来自 JAX-RS 的 @Produces 和 @Consumes。
没有直接关系，但是升级到 Springfox 的 2.6.0 版本在 bug 方面会有更好的体验。 :)

标签： rest spring-boot swagger swagger-ui

【解决方案1】：

您可能需要一个资源处理程序。可能是这样的：

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

【讨论】：

我应该在哪里添加这个 sn-p？
@Vishwas 创建一个扩展 WebMvcConfigurerAdapter 的类并用 @EnableWebMvc 注释它。
感谢您的回复。让我试试这个。
@CássioMazzochiMolin 您不应该在 springboot 中执行此操作。自动配置会解决这个问题。

【解决方案2】：

我认为您必须在 @SpingBootApplication 注释之前将 @EnableSwagger2 与您的 @Configuration 注释类一起使用。仔细看看这个article

尝试添加 .paths(PathSelectors.any()) ：

    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                           
    }

【讨论】：