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
    private OrderServiceFeign orderServiceFeign;

    @ApiOperation("方法描述用例")
    @PostMapping("/swaggerIndex")
    public String swaggerMember() {
        return "swaggerIndex";
    }

    @ApiOperation("參數描述用例")
    @ApiImplicitParam(name = "name", value = "用戶名", required = true, dataTypeClass = String.class)
    @GetMapping("/getAge")
    public String swaggerMemberParam(String userName) {
        return "chris";
    }

    @RequestMapping("/")
    public String index() {
        return "app-aiyuesheng-member";
    }

    // @HystrixCommand 默認開啟服務隔離，是以線程池方式
    // @HystrixCommand 默認開啟服務降級，fallbackMethod 方法名就是服務的降級名稱
    // @HystrixCommand 默認開啟服務熔斷機制
    // @Hystrix 要禁止超時時間，默認1 秒，如果沒有即使響應，會走業務邏輯，但是也會走服務降級方法，所以要禁止超時時間
    @HystrixCommand(fallbackMethod = "orderServiceFallback")
    @RequestMapping("/getOrder")
    public Order getOrder(String orderId) {
        System.out.println("orderToUserInfo:" + "當前線程池名稱:" + Thread.currentThread().getName());
        return orderServiceFeign.getOrder(orderId);
    }

    @RequestMapping("/getOrder2")
    public Order getOrder2(String orderId) {
        System.out.println("orderToUserInfo:" + "當前線程池名稱:" + Thread.currentThread().getName());
        return orderServiceFeign.getOrder(orderId);
    }

    @RequestMapping("/orderServiceFallback")
    public String orderServiceFallback() {
        return "服務器繁忙，請稍后重試";
    }

}

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("方法描述用例")
    @PostMapping("/swaggerIndex")
    public String swaggerOrder() {
        return "swaggerIndex";
    }

    @ApiOperation("參數描述用例")
    @ApiImplicitParam(name = "name", value = "用戶名", required = true, dataTypeClass = String.class)
    @GetMapping("/getAge")
    public String swaggerOrderrParam(String userName) {
        return "chris";
    }

    @RequestMapping("/")
    public String index() {
        return "app-aiyuesheng-order";
    }

    @RequestMapping("/getOrder")
    public Order getOrder(String orderId) {
        Order order = new Order();
        order.setOrderId(orderId);
        order.setOrderName("訂單名稱");
        return order;
    }

}

父類：

@Api("訂單接口文檔")
public interface IOrderService {
    
    @RequestMapping("/getOrder")
    public 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，然后再轉發到對應的服務地址的