Springboot整合Swagger及踩坑记录

1 整合步骤

1.1 引入依赖

特别注意版本问题,好几次整合都倒在版本上面.不想折腾的话,请保持版本和我的一致

<!-- swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> <exclusions> <exclusion> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> <version>1.6.0</version> </dependency> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.5</version> </dependency>

1.2 增加配置类

尤其注意,配置类应在启动类同级目录及同级目录子目录下才能被扫描到.

package xyz.yq56.common.config; import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; 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 @EnableSwaggerBootstrapUI public class Swagger2Config { @Value("${spring.application.name:demo}") private String name; @Value("${swagger.docket.basePackage:xyz.yq56}") private String basePackage; @Bean public Docket docket() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage(basePackage)) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("微服务 -" + name +"- APIs　说明和调试　") .description("") .termsOfServiceUrl("") .version("1.0") .build(); } }

1.3 Springcloud配置实例地址

application.yml中添加配置eureka.instance.status-page-url,完整配置如下:

server: port: 9001 spring: application: name: FAKE-DATA eureka: client: serviceUrl: defaultZone: http://192.168.33.193:8761/eureka/ instance: status-page-url: http://localhost:${server.port}/doc.html swagger: docket: basePackage: xyz.yq56

2 具体使用

主要涉及三个注解:@Api,@ApiOperation,@ApiImplicitParams,分别对应类,方法和参数

package xyz.yq56.fakedata.controller; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import org.apache.commons.io.IOUtils; import org.springframework.util.ResourceUtils; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.io.File; import java.io.FileInputStream; import java.io.IOException; import java.nio.charset.StandardCharsets; /** * @author yq */ @Api(value = "technical",tags = "技战法") @RestController @RequestMapping("/technical") public class Json2Controller { @ApiOperation(value = "碰撞") @PostMapping(value = "/collision") public String collision() throws IOException { File file = ResourceUtils.getFile(ResourceUtils.CLASSPATH_URL_PREFIX+ "data/json/collision.json"); return IOUtils.toString(new FileInputStream(file), String.valueOf(StandardCharsets.UTF_8)); } @ApiOperation(value = "频次") @PostMapping(value = "/frequency") public String frequency() throws IOException { File file = ResourceUtils.getFile(ResourceUtils.CLASSPATH_URL_PREFIX+ "data/json/frequency2.json"); return IOUtils.toString(new FileInputStream(file), String.valueOf(StandardCharsets.UTF_8)); } }

3 效果展示

大致效果如下:

4 踩坑

4.1 显示空白页

问题如下图所示 解决方案

配置类没生效:最大可能就是配置类不在启动类同级目录和下级目录下,导致没扫描到配置类中包名写错了依赖版本问题,尽可能跟我保持一致