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

巴特西

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

最新文章

热门文章