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 "服务器繁忙，请稍后重试";
    }

}

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("方法描述用例")
    @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;
    }

}

View Code

父类：

@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，然后再转发到对应的服务地址的

posted @ 2019-08-22 17:41 Chris,Cai 阅读(6373) 评论(0) 编辑收藏举报

刷新页面返回顶部

Chris,Cai

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

公告