swagger2 接口文档,整个微服务接口文档

1，因为整个微服务会有好多服务，比如会员服务，支付服务，订单服务，每个服务都集成了swagger

     我们在访问的时候，不可能每个服务输入一个url 去访问，看起来很麻烦，所以我们需要在一个页面上集成整个微服务项目中所有的 swagger

     效果图：可以选择不同的应用，出来的是不同的swagger 接口文档

2，实现思路：

    zuul 网关 + swagger 

    客户端访问一个应用，zuul 网关转发到相应的界面，看起来是在一个服务上的效果  

3，eureka ：注册中心

     springcloud-config:注册中心：路由转发用配置中心做的，没有写在本地。可以参考springcloud-config 动态网关路由

     springcloud-api-member-impl-service:在eureka 注册的服务是：app-aiyuesheng-member

     springcloud-api-order-impl-service:在eureka 注册的服务是：app-aiyuesheng-order

     springcloud-swagger2:swagger 服务

     springcloud-zuul :zuul 网关服务

4，

第一步：

member 服务 和 order ，zuul 需要添加maven 依赖：

        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.7.0.RELEASE</version>
        </dependency>

第二步：   

member ,order 配置文件添加：

##swagger扫包
swagger:
  base-package: com.aiyuesheng.api.impl

第三步：

swagger 的接口类的写法还是一样：

package com.aiyuesheng.api.impl;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.aiyuesheng.entity.Order;
import com.aiyuesheng.feign.OrderServiceFeign;
import com.netflix.hystrix.contrib.javanica.annotation.HystrixCommand;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

@RestController
@Api(“会员接口文档”)
public class MemberServiceImpl {

@Autowired
</span><span style="color: #0000ff;">private</span><span style="color: #000000;"> OrderServiceFeign orderServiceFeign;

@ApiOperation(</span>"方法描述用例"<span style="color: #000000;">)
@PostMapping(</span>"/swaggerIndex"<span style="color: #000000;">)
</span><span style="color: #0000ff;">public</span><span style="color: #000000;"> String swaggerMember() {
    </span><span style="color: #0000ff;">return</span> "swaggerIndex"<span style="color: #000000;">;
}

@ApiOperation(</span>"参数描述用例"<span style="color: #000000;">)
@ApiImplicitParam(name </span>= "name", value = "用户名", required = <span style="color: #0000ff;">true</span>, dataTypeClass = String.<span style="color: #0000ff;">class</span><span style="color: #000000;">)
@GetMapping(</span>"/getAge"<span style="color: #000000;">)
</span><span style="color: #0000ff;">public</span><span style="color: #000000;"> String swaggerMemberParam(String userName) {
    </span><span style="color: #0000ff;">return</span> "chris"<span style="color: #000000;">;
}

@RequestMapping(</span>"/"<span style="color: #000000;">)
</span><span style="color: #0000ff;">public</span><span style="color: #000000;"> String index() {
    </span><span style="color: #0000ff;">return</span> "app-aiyuesheng-member"<span style="color: #000000;">;
}

</span><span style="color: #008000;">//</span><span style="color: #008000;"> @HystrixCommand 默认开启服务隔离，是以线程池方式
</span><span style="color: #008000;">//</span><span style="color: #008000;"> @HystrixCommand 默认开启服务降级，fallbackMethod 方法名就是服务的降级名称
</span><span style="color: #008000;">//</span><span style="color: #008000;"> @HystrixCommand 默认开启服务熔断机制
</span><span style="color: #008000;">//</span><span style="color: #008000;"> @Hystrix 要禁止超时时间，默认1 秒，如果没有即使响应，会走业务逻辑，但是也会走服务降级方法，所以要禁止超时时间</span>
@HystrixCommand(fallbackMethod = "orderServiceFallback"<span style="color: #000000;">)
@RequestMapping(</span>"/getOrder"<span style="color: #000000;">)
</span><span style="color: #0000ff;">public</span><span style="color: #000000;"> Order getOrder(String orderId) {
    System.out.println(</span>"orderToUserInfo:" + "当前线程池名称:" +<span style="color: #000000;"> Thread.currentThread().getName());
    </span><span style="color: #0000ff;">return</span><span style="color: #000000;"> orderServiceFeign.getOrder(orderId);
}

@RequestMapping(</span>"/getOrder2"<span style="color: #000000;">)
</span><span style="color: #0000ff;">public</span><span style="color: #000000;"> Order getOrder2(String orderId) {
    System.out.println(</span>"orderToUserInfo:" + "当前线程池名称:" +<span style="color: #000000;"> Thread.currentThread().getName());
    </span><span style="color: #0000ff;">return</span><span style="color: #000000;"> orderServiceFeign.getOrder(orderId);
}

@RequestMapping(</span>"/orderServiceFallback"<span style="color: #000000;">)
</span><span style="color: #0000ff;">public</span><span style="color: #000000;"> String orderServiceFallback() {
    </span><span style="color: #0000ff;">return</span> "服务器繁忙，请稍后重试"<span style="color: #000000;">;
}

}

View Code

order 因为之前由feign 客户端调用，所以在父类里面也要加@Api()注解：

package com.aiyuesheng.api.impl;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.aiyuesheng.api.IOrderService;
import com.aiyuesheng.entity.Order;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

@RestController
@Api(“订单接口文档”)
public class OrderServiceImpl implements IOrderService {

@ApiOperation(</span>"方法描述用例"<span style="color: #000000;">)
@PostMapping(</span>"/swaggerIndex"<span style="color: #000000;">)
</span><span style="color: #0000ff;">public</span><span style="color: #000000;"> String swaggerOrder() {
    </span><span style="color: #0000ff;">return</span> "swaggerIndex"<span style="color: #000000;">;
}

@ApiOperation(</span>"参数描述用例"<span style="color: #000000;">)
@ApiImplicitParam(name </span>= "name", value = "用户名", required = <span style="color: #0000ff;">true</span>, dataTypeClass = String.<span style="color: #0000ff;">class</span><span style="color: #000000;">)
@GetMapping(</span>"/getAge"<span style="color: #000000;">)
</span><span style="color: #0000ff;">public</span><span style="color: #000000;"> String swaggerOrderrParam(String userName) {
    </span><span style="color: #0000ff;">return</span> "chris"<span style="color: #000000;">;
}

@RequestMapping(</span>"/"<span style="color: #000000;">)
</span><span style="color: #0000ff;">public</span><span style="color: #000000;"> String index() {
    </span><span style="color: #0000ff;">return</span> "app-aiyuesheng-order"<span style="color: #000000;">;
}

@RequestMapping(</span>"/getOrder"<span style="color: #000000;">)
</span><span style="color: #0000ff;">public</span><span style="color: #000000;"> Order getOrder(String orderId) {
    Order order </span>= <span style="color: #0000ff;">new</span><span style="color: #000000;"> Order();
    order.setOrderId(orderId);
    order.setOrderName(</span>"订单名称"<span style="color: #000000;">);
    </span><span style="color: #0000ff;">return</span><span style="color: #000000;"> order;
}

}

View Code

父类：

@Api("订单接口文档")
public interface IOrderService {
@RequestMapping(</span>"/getOrder"<span style="color: #000000;">)
</span><span style="color: #0000ff;">public</span><span style="color: #000000;"> Order getOrder(String orderId);

}

第四步：

启动类加上注解@EnableSwagger2Doc

@SpringBootApplication
@EnableEurekaClient
@EnableFeignClients
@EnableSwagger2Doc    //生成swagger文档
public class OrderApp {
    public static void main(String[] args) {
        SpringApplication.run(OrderApp.class, args);
    }
}

第五步：配置zuul:

package com.aiyuesheng;

import java.util.ArrayList;
import java.util.List;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.cloud.netflix.zuul.EnableZuulProxy;
import org.springframework.cloud.netflix.zuul.filters.ZuulProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;

import com.spring4all.swagger.EnableSwagger2Doc;

import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;

@EnableZuulProxy
@SpringBootApplication
@EnableDiscoveryClient
@EnableSwagger2Doc
public class ZuulApplication {
public static void main(String[] args) {
SpringApplication.run(ZuulApplication.class, args);
}
// @Bean
// public TokenFilter accessFilter() {
// return new TokenFilter();
// }

@RefreshScope
@ConfigurationProperties(“zuul”)
public ZuulProperties zuulProperties() {
return new ZuulProperties();
}
}

@Component
@Primary
class DocumentationConfig implements SwaggerResourcesProvider {
@Override
public List<SwaggerResource> get() {
List resources = new ArrayList<>();
resources.add(swaggerResource(“app-aiyuesheng-member”, “/api-member/v2/api-docs”, “2.0”));
resources.add(swaggerResource(“app-aiyuesheng-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;
}

}

zuul 的配置文件，回顾下，

spring:
  application:
    ####注册中心应用名称
    name:  service-zuul
  cloud:
    config:
    ####读取后缀
      profile: dev
      ####读取config-server注册地址
      discovery:
        service-id: config-server
        enabled: true
#####eureka服务注册地址    
eureka:
  client:
    service-url:
           defaultZone: http://localhost:8100/eureka    
server:
  port: 80

#配置手动实时刷新
#managementendpoints.web.exposure.include=*
management:
endpoints:
web:
exposure:
include: “*”

配置中心上的路由转发，回顾下：

### 配置网关反向代理    
zuul:
  routes:
    api-member:
     ### 以 /api-member/访问转发到会员服务
      path: /api-member/**
      serviceId: app-aiyuesheng-member
    api-order:
        ### 以 /api-order/访问转发到订单服务
      path: /api-order/**
      serviceId: app-aiyuesheng-order

 配置成功：访问http://127.0.0.1/swagger-ui.html#/ 

因为网关是80，然后再转发到对应的服务地址的