微服务之整合Swagger接口文档

Maven依赖配置

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

网关配置Swagger

网关依赖依赖配置

<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-gateway</artifactId>
        <version>2.2.1.RELEASE</version>
    </dependency>
</dependencies>

swagger配置文件 – config

@Component
@Primary
@AllArgsConstructor
public class SwaggerProvider implements SwaggerResourcesProvider {
    public static final String API_URI = "/v2/api-docs";
    private final RouteLocator routeLocator;
    private final GatewayProperties gatewayProperties;


    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<>();
        List<String> routes = new ArrayList<>();
        routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));
        gatewayProperties
        .getRoutes()
        .stream()
        .filter(routeDefinition -> routes.contains(routeDefinition.getId()))
           .forEach(routeDefinition -> routeDefinition.getPredicates().stream()
             .filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName()))
                        .forEach(predicateDefinition -> resources.add(swaggerResource(routeDefinition.getId(),
                                predicateDefinition.getArgs().get(NameUtils.GENERATED_NAME_PREFIX + "0")
                                        .replace("/**", API_URI)))));
        return resources;
    }

    private SwaggerResource swaggerResource(String name, String location) {
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion("2.0");
        return swaggerResource;
    }
}

Swagger过滤器 – filter

@Component
@Deprecated
public class SwaggerHeaderFilter extends AbstractGatewayFilterFactory {
    private static final String HEADER_NAME = "X-Forwarded-Prefix";

    @Override
    public GatewayFilter apply(Object config) {
        return (exchange, chain) -> {
            ServerHttpRequest request = exchange.getRequest();
            String path = request.getURI().getPath();
            if (!StringUtils.endsWithIgnoreCase(path, SwaggerProvider.API_URI)) {
                return chain.filter(exchange);
            }

            String basePath = path.substring(0, path.lastIndexOf(SwaggerProvider.API_URI));


            ServerHttpRequest newRequest = request.mutate().header(HEADER_NAME, basePath).build();
            ServerWebExchange newExchange = exchange.mutate().request(newRequest).build();
            return chain.filter(newExchange);
        };
    }
}

Swagger控制层 – handler

@RestController
@RequestMapping("/swagger-resources")
public class SwaggerHandler {
    @Autowired(required = false)
    private SecurityConfiguration securityConfiguration;
    @Autowired(required = false)
    private UiConfiguration uiConfiguration;
    private final SwaggerResourcesProvider swaggerResources;

    @Autowired
    public SwaggerHandler(SwaggerResourcesProvider swaggerResources) {
        this.swaggerResources = swaggerResources;
    }


    @GetMapping("/configuration/security")
    public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {
        return Mono.just(new ResponseEntity<>(
                Optional.ofNullable(securityConfiguration)
                .orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK));
    }

    @GetMapping("/configuration/ui")
    public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {
        return Mono
        .just(new ResponseEntity<>(
                Optional.ofNullable(uiConfiguration)
                .orElse(UiConfigurationBuilder.builder().build())
                , HttpStatus.OK));
    }

    @GetMapping("")
    public Mono<ResponseEntity> swaggerResources() {
        return Mono
        .just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));
    }
}

配置文件yaml

server:
  port: 81
spring:
  cloud:
    nacos:
      discovery:
        ##服务注册
        server-addr: 127.0.0.1:8848
    gateway:
      locator:
        enabled: true
      routes:
        - id: mayikt-weixin
          uri: lb://mayikt-weixin
          predicates:
            - Path=/mayikt-weixin/**
          filters:
            - SwaggerHeaderFilter
            - StripPrefix=1
        - id: mayikt-member
          uri: lb://mayikt-member
          predicates:
            - Path=/mayikt-member/**
          filters:
            - SwaggerHeaderFilter
            - StripPrefix=1
      x-forwarded:
        enabled: false

  application:
    name: mayikt-gateway

子系统对接网关接口文档

配置文件 – yaml

swagger:
  base-package: com.zly.api.member.impl.service
  title: SpringCloud2.x微服项目 -- 会员服务
  description: 配置
  version: 1.1
  terms-of-service-url: www.zly.com
  contact:
    name: 张良源
    email: 747485114@qq.com
    url: www.zly.com
  enabled: true
  

接口使用Swagger注解

@Api(tags = "微信基本服务接口")
public interface WeiXinService {

    /***
     *  微信接口
     * @return
     */
    @GetMapping("appInfo")
    @ApiOperation("appInfo接口")
    @ApiImplicitParam(name = "userId", value = "用户的id", required = true)
    @ApiResponses({@ApiResponse(code = 200, message = "成功"), @ApiResponse(code = 500, message = "失败")})
    String appInfo(@RequestParam("userId") Long userId);


    /**
     * appid 和appSecret
     *
     * @param appId
     * @param appSecret
     * @return
     */
    @GetMapping("getApp")
    @ApiOperation("getApp接口")
    @ApiImplicitParams({@ApiImplicitParam(name = "appId", value = "应用的id", required = true),
            @ApiImplicitParam(name = "appSecret", value = "应用的密钥", required = true)})
    @ApiResponses({@ApiResponse(code = 200, message = "成功"), @ApiResponse(code = 500, message = "失败")})

    BaseResponse<String> getApp(@RequestParam("appId") String appId, @RequestParam("appSecret") String appSecret);
//    BaseResponse<String> getApp(String appId, String appSecret);


}

Swagger配置说明

注解	用途
@Api	用在请求的类上，表示对类说明
tags	说明该类的作用，可以在UI界面上看到的注解
value	该参数没什么意义，在UI界面上也看到,所以不需要配置
@ApiOperation	用在请求的方法上，说明方法的用途、作用
vaule	说明方法的用途、作用
notes	方法的备注说明
@ApiImplicitParams	用在请求的方法上，表示一组参数说明
@ApiImplicitParam	用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name	参数名
value	参数的汉字说明、解释
required	参数是否必须传
paramType	参数放在哪个地方
header	请求参数的获取：@RequestHeader
query	请求参数的获取：@RequestParam
path（用于restful接口）	请求参数的获取：@PathVariable
dataType	参数类型，默认String，其它值dataType=“Integer”
defaultValue	参数的默认值
@ApiResponses	用在请求的方法上，表示一组响应
@ApiResponse	用在@ApiResponses中，一般用于表达一个错误的响应信息
code	数字，例如400
message	信息，例如"请求参数没填好"
response	抛出异常的类
@ApiModel	用于响应类上，表示一个返回响应数据的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty	用在属性上，描述响应类的属性

配置启动类

@EnableSwagger2Doc

-------资源转载于蚂蚁课堂(www.mayikt.com)