1.代码地址
链接:https://pan.baidu.com/s/1KbVTpA5BuRlNzKESTj4Y-A
提取码:y0yx
2.Swagger好处在哪里
传统开发的几个痛处
- 对API文档进行更新的时候,需要通知前端开发人员,导致文档更新交流不及时;
- API接口返回信息不明确
- 大公司中肯定会有专门文档服务器对接口文档进行更新。
- 缺乏在线接口测试,通常需要使用相应的API测试工具,比如postman、SoapUI等
- 接口文档太多,不便于管理
Swagger具有以下优点
- 功能丰富:支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能;
- 及时更新:开发过程中花一点写注释的时间,就可以及时的更新API文档,省心省力;
- 整合简单:通过添加pom依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务。
为了解决传统API接口文档维护的问题,为了方便进行测试后台Restful接口并实现动态的更新,因而引入Swagger接口工具。
3.SpringBoot整合Swagger
1. 依赖文件
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.0.1.RELEASE</version>
</parent>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>Finchley.M7</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<!-- SpringBoot整合Web组件 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- SpringBoot整合eureka客户端 -->
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>
<!-- swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
</dependencies>
<!-- 注意: 这里必须要添加, 否者各种依赖有问题 -->
<repositories>
<repository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>https://repo.spring.io/libs-milestone</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
</project>
2.配置文件
@Configuration
//开启swagger功能
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
// 生成扫包的范围
.apis(RequestHandlerSelectors.basePackage("com.disney.api")).paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("微服务电商系统").description("Java分布式")
.termsOfServiceUrl("http://www.baidu.com")
// 文档的版本号
.version("1.0").build();
}
}
3. controller
@RestController
//对于的接口的描述
@Api("测试控制器")
public class SwaggerController {
@ApiOperation("swagger接口")
@GetMapping("/index") //这里尽可能用restful风格的请求路径,不然写requestMapping的话,任何的形式的请求都会有,很乱
public String getIndex(){
return "index";
}
}
4.启动类
@SpringBootApplication
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class,args);
}
}
访问http://localhost:8989/swagger-ui.html#/swagger-controller 即可看到如下界面
4.参数的生成
@ApiOperation("参数的获取")
@GetMapping("/getname")
@ApiImplicitParam(name = "name",value = "用户参数",required = true,dataType = "String")
public String getName(String name){
return name;
}
5.微服务网关Zuul集群整合Swagger
所面临的的问题: Swagger是针对单独所在项目接口进行生成,那么微服务的所有服务的接口,如何整合在一起呢?
相关的SpirngCloud Zuul网关的可以参考https://blog.csdn.net/qq_42292373/article/details/103227925
- 分别在Member和Order项目,Zuul网关 添加依赖
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.7.0.RELEASE</version>
</dependency>
2,启动类改变(Order 和Member )
@SpringBootApplication
@EnableFeignClients
@EnableEurekaClient
@EnableHystrix
//生成swagger文档
@EnableSwagger2Doc
public class AppOrder {
public static void main(String[] args) {
SpringApplication.run(AppOrder.class, args);
}
}
3.增加扫描接口的路径
###服务启动端口号
server:
port: 8020
###服务名称(服务注册到eureka名称)
spring:
application:
name: app-itmayiedu-order
###服务注册到eureka地址
eureka:
client:
service-url:
defaultZone: http://localhost:8100/eureka
###因为该应用为注册中心,不会注册自己
register-with-eureka: true
###是否需要从eureka上获取注册信息
fetch-registry: true
###设置feign客户端超时时间
ribbon:
###指的是建立连接所用的时间,适用于网络状况正常的情况下,两端连接所用的时间。
ReadTimeout: 5000
###指的是建立连接后从服务器读取到可用资源所用的时间。
ConnectTimeout: 5000
#feign:
# hystrix:
#enabled: true
swagger:
base-package: com.member.impl # 扫描的路径
4,对接口的说明
@RestController
@Api("订单服务接口")
public class OrderServiceImpl implements IOrderService {
@Autowired
private MemberServiceFeigin memberServiceFeigin;
@RequestMapping("/orderToMember")
public String orderToMember(String name) {
UserEntity user = memberServiceFeigin.getMember(name);
return user == null ? "没有找到用户信息" : user.toString();
}
// @HystrixCommand(fallbackMethod = "fallbackMethod")
@ApiOperation("getIndex")
@RequestMapping("/getIndex")
public String getIndex(){
return memberServiceFeigin.getIndex();
}
public String fallbackMethod(){
return "对不起当前方法不可用";
}
}
- 在Zuul网关服务中添加配置和启动类的修改
@SpringBootApplication
@EnableEurekaClient
@EnableZuulProxy
@EnableSwagger2Doc
public class ZuulApplication {
public static void main(String[] args) {
SpringApplication.run(ZuulApplication.class,args);
}
@RefreshScope
@ConfigurationProperties("zuul")
public ZuulProperties zuulProperties(){
return new ZuulProperties();
}
// 添加文档来源
@Component
@Primary
class DocumentationConfig implements SwaggerResourcesProvider {
@Override
public List<SwaggerResource> get() {
List resources = new ArrayList<>();
//arg 根据服务别名,确定文档的目标
//arg1 通过网关进行查询API文档
//arg2
resources.add(swaggerResource("app-itmayiedu-member", "/api-member/v2/api-docs", "2.0"));
resources.add(swaggerResource("app-itmayiedu-order", "/api-order/v2/api-docs", "2.0"));
return resources;
}
private SwaggerResource swaggerResource(String name, String location, String version) {
SwaggerResource swaggerResource = new SwaggerResource();
swaggerResource.setName(name);
swaggerResource.setLocation(location);
swaggerResource.setSwaggerVersion(version);
return swaggerResource;
}
}
}
然后访问http://localhost:81/swagger-ui.html或者http://localhost:82/swagger-ui.html 任意网关端口号,即可看到如下的界面
注意:如果有ZullFilter的话,可能会出现这个界面,所以上面的图片,我注释掉了ZuulFilter,也请各位大佬,可以分享下这个解决问题的建议,在这里,提前谢谢你们