swagger笔记

介绍

• swagger是用来管理api的开源项目
• 可以用来给团队共享api文档和提供测试api接口的工具
• 文档和测试工具会随着代码的更新而更新
• 只需要很少的配置就能实现

模块

• swagger分为swagger模块和swagger-ui模块　前后端分离

版本选择

springfox

• 目前最新版本2.9.2
• 接受或返回map时　需要借助bean对象或插件(有缺陷)使接口文档中包含具体的参数和返回字段
• api ui是以上下滚动折叠框分组的形式提供的
• 不符合国人习惯
• 不过习惯吗用着用着就改变了
• 最重要的是api测试功能输入没有记忆功能
• 重新进入网页后再次测试相同的接口参数没有提示功能 这要这么搞
• 当你需要同时测试多个接口时这感觉很酸爽　因为没有面包屑 你会迷失在滚动的海洋

xiaoymin

• 核心还是使用的swagger 把swagger-ui换了 在加了些曾强功能
• 提供独立的注解来解决map问题
• ui符合国人习惯 左右分栏
• 测试有输入记忆功能
• 有面包屑需要同时请求多个接口也方便
• 对于我这种把测试接口当ui来用的人来说还是蛮好用的

使用

• 分文单应用和多应用两种情况

依赖部分

• springfox

  
  <dependency>
  	<groupId>io.springfoxgroupId>
  	<artifactId>springfox-swagger2artifactId>
  	<version>2.9.2version>
  dependency>
  
  <dependency>
  	<groupId>io.springfoxgroupId>
  	<artifactId>springfox-swagger-uiartifactId>
  	<version>2.9.2version>
  dependency>
  

• xiaoymin

  
  <dependency>
  	<groupId>com.github.xiaoymingroupId>
  	<artifactId>knife4j-spring-boot-starterartifactId>
  	<version>2.0.2version>
  dependency>
  
   <dependency>
  	<groupId>com.github.xiaoymingroupId>
  	<artifactId>knife4j-micro-spring-boot-starterartifactId>
  dependency>
  

• 注意事项

  org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NoSuchMethodError: com.google.common.collect.FluentIterable.append(Ljava/lang/Iterable;)Lcom/google/common/collect/FluentIterable;
  at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:184) ~[spring-context-5.0.8.RELEASE.jar:5.0.8.RELEASE]
  Caused by: java.lang.NoSuchMethodError: com.google.common.collect.FluentIterable.append(Ljava/lang/Iterable;)Lcom/google/common/collect/FluentIterable;
  

  如果运行时报上面的错那是
  因为默认引入的瓜娃子版本太低 缺少方法要升级瓜娃子

  <dependency>
  	<groupId>com.google.guavagroupId>
  	<artifactId>guavaartifactId>
  	<version>29.0-jreversion>
  dependency>
  

  如果加入上面的依赖还是不行　那就因为该瓜娃子进入欠收拾模式　需要你调教下
  可以看下依赖里面是不是有冲突有多个guava子版本　把低版本的排除掉
  可以借助idea的project structure的modules的依赖下删除低版本的瓜娃子 或者mvn依赖分析　在手工排除

代码部分

• 单应用

  • 直接引用依赖 创建个Docket(这名字貌似很牛逼啊)交给spring管理 开启swagger

  @EnableKnife4j //knife4j独有　提供增强功能
  @EnableSwagger2
  @Configuration
  @Profile({"dev","test","local","tt"})
  public class SwaggerConfig {
  
      @Bean
      @Order(value = 1)
      public Docket groupRestApi() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  .select()
              .apis(RequestHandlerSelectors.basePackage("com.xiaominfo.swagger.service.user.controller"))
              .paths(PathSelectors.any())
              .build()
              //　用来设置Authorization和Authorization-x用来token访问
              .securityContexts(Lists.newArrayList(securityContext(),securityContext1()))
              .securitySchemes(Lists.<SecurityScheme>newArrayList(apiKey(),apiKey1()));
      }
  
      private ApiInfo apiInfo(){
          return new ApiInfoBuilder()
                  .title("api文档")
                  .description("
  api文档
  ")
                  .termsOfServiceUrl("http://www.shangtian.com/")
                  .contact("[email protected]")
                  .version("1.0")
                  .build();
      }
      
  	 private ApiKey apiKey() {
          return new ApiKey("BearerToken", "Authorization", "header");
      }
      
      private ApiKey apiKey1() {
          return new ApiKey("BearerToken1", "Authorization-x", "header");
      }
  
      private SecurityContext securityContext() {
          return SecurityContext.builder()
                  .securityReferences(defaultAuth())
                  .forPaths(PathSelectors.regex("/.*"))
                  .build();
      }
      private SecurityContext securityContext1() {
          return SecurityContext.builder()
                  .securityReferences(defaultAuth1())
                  .forPaths(PathSelectors.regex("/.*"))
                  .build();
      }
  
      List<SecurityReference> defaultAuth() {
          AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
          AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
          authorizationScopes[0] = authorizationScope;
          return Lists.newArrayList(new SecurityReference("BearerToken", authorizationScopes));
      }
      List<SecurityReference> defaultAuth1() {
          AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
          AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
          authorizationScopes[0] = authorizationScope;
          return Lists.newArrayList(new SecurityReference("BearerToken1", authorizationScopes));
      }
  }
  

• 多应用

  • 可以在每个应用按照单应用的来

  • 但是这样一来如果有20个工程或者更多的话　访问起来这滋味应该相当的爽

  • 要提供api文档的所有服务都引用swagger模块

  • 需要提供访问swagger界面的服务引用swagger-ui模块　并且提供路由信息　通常为网关服务

  • 如果是其他服务需要收集路由信息　可以是到网关或注册中心获取　获取广播采集　再不济采用录入方式

  • 步骤为根据路由信息生成接口请求地址　-> 　根据请求地址请求目标服务接口

  • 这样就解决了需要访问多个服务的api时需要开多个网站的问题

  • 假如现在有５个服务除了注册中心其他需要提供api文档 服务如下

  • １个注册中心　1个user服务 　1个订单服务　１个商品服务　１个网关服务(zuul)

  • 注册中心不用管　user、订单、商品服务 引入服务端依赖 按单应用的配置走

  • 网关服务引入服务端和ui依赖　配置如下

  @EnableSwagger2
  @Configuration
  @Profile({"dev","test","local","tt"})
  public class SwaggerConfig {
  
      @Bean
      @Order(value = 1)
      public Docket groupRestApi() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo());
      }
  
      private ApiInfo apiInfo(){
          return new ApiInfoBuilder()
                  .title("api文档")
                  .description("
  api文档
  ")
                  .termsOfServiceUrl("http://www.shangtian.com/")
                  .contact("[email protected]")
                  .version("1.0")
                  .build();
      }
  }
  

  @Component
  @Primary
  @Profile({"dev","test","local","tt"})
  public class SwaggerResourceConfig implements SwaggerResourcesProvider {
  
      Logger logger= LoggerFactory.getLogger(SwaggerResourceConfig.class);
  
  
      @Autowired
      RouteLocator routeLocator;
  
      @Override
      public List<SwaggerResource> get() {
          //获取所有router
          List<SwaggerResource> resources = new ArrayList<>();
          List<Route> routes = routeLocator.getRoutes();
          logger.info("Route Size:{}",routes.size());
          for (Route route:routes) {
              resources.add(swaggerResource(route.getId(), route.getFullPath().replace("**", "v2/api-docs")));
          }
          return resources;
      }
      private SwaggerResource swaggerResource(String name, String location) {
          logger.info("name:{},location:{}",name,location);
          SwaggerResource swaggerResource = new SwaggerResource();
          swaggerResource.setName(name);
          swaggerResource.setLocation(location);
          swaggerResource.setSwaggerVersion("1.0");
          return swaggerResource;
      }
  }
  

  • 通过上面的配置就可以通过网关访问user、订单、商品服务的api文档了
  • 如果网关服务不是zuul或者没有网关　可以借助nginx的反向代理 　在实现对应的SwaggerResourceConfig就行了

资料文献

knife4j项目说明

swagger使用示例

springfox