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 显示空白页
问题如下图所示
解决方案
- 配置类没生效:最大可能就是配置类不在启动类同级目录和下级目录下,导致没扫描到
- 配置类中包名写错了
- 依赖版本问题,尽可能跟我保持一致