SpringBoot集成Swagger3，还想来份离线文档？真酷炫

架构 2023-07-05 17:29:38

58阅读

序言

伴随着新项目构架的演变，前后端分离是无法阻挡的发展趋势。这类方式的合作在实践活动的全过程中常常会碰到的一个难题便是文本文档。

在《一位CTO告诉我，项目中至少需要这3类文档》一文大家早已叙述了文本文档的必要性，而api文档就是在其中之一，能够说成不可或缺的。

但撰写api文档对开发者而言是一大难点，并且插口仍在持续的转变，也要耗费活力去维护保养api文档的升级。

即然存有困扰，那麼务必会发生处理此困扰的商品，这就是Swagger，现阶段早已升级到Swagger3版本号了。假如你要滞留在Swagger2，提议升級到Swagger3，总体UI设计风格及互动友善了许多。

这篇将紧紧围绕Swagger3与SpringBoot的集成化和线下文本文档的转化成来开展解读。

Swagger介绍

Swagger是一个标准和详细的架构，用以转化成、叙述、启用和数据可视化RESTful设计风格的Web服务。目标是使手机客户端和系统文件做为网络服务器以一样的速率来升级。文档的方式，主要参数和实体模型密切集成化到服务端的编码，容许API来持续保持同歩。

官方网站：https://swagger.io

Swagger处理的困扰

传统式方法出示文本文档有下列困扰：

插口诸多，完成关键点繁杂，撰写文本文档消耗费劲，必须不断维护保养;
api文档必须随时随地开展同歩;
插口回到的結果不确立，得结构回到建筑结构等;
不可以立即线上测试接口，一般必须附加的专用工具，例如PostMan等。

当引进Swagger以后，之上困扰得到解决，另外还产生下列优势：

时效性 (插口变动后，前后左右端工作人员可即时见到最新版)
规范化 (插口实际统一设计风格，如插口详细地址，要求方法，主要参数，回应文件格式和错误报告等)
一致性 (插口信息内容一致，不容易因api文档版本号难题产生分歧)
可测性 (可立即根据api文档开展检测)

Swagger3的更改

Swagger3.0的修改，官方网文本文档汇总以下几个方面：

删除了对springfox-swagger2的依靠;
删掉全部@EnableSwagger2...注释;
加上了springfox-boot-starter依靠项;
移除开guava等第三方依靠;
文本文档浏览详细地址改成http://ip:port/project/swagger-ui/index.html。

下边就来实战演练应用一下吧。

SpringBoot集成化Swagger3

SpringBoot集成化Swagger3与SpringBoot集成化别的架构的招数基本一致，一般包含：引进依靠、特定环境变量、建立配备类和应用。

引进依靠

在SpringBoot新项目的pom.xml中引进Swagger3依靠：

 
  <dependency> 
      <groupId>io.springfox</groupId> 
      <artifactId>springfox-boot-starter</artifactId> 
      <version>3.0.0</version> 
  </dependency>

特定环境变量

一般状况下swagger只有在开发工具或接口测试下打开，工作环境下必须开展关掉的。而swagger的打开与关掉可在application.properties中开展配备：

 
  # 工作环境需设定为false 
  springfox.documentation.swagger-ui.enabled=true

配备类

根据@EnableOpenApi注释运行用Swagger的应用，另外在配备类中对Swagger的通用性主要参数开展配备。

 
  @Configuration 
  @EnableOpenApi 
  public class Swagger3Config { 
   
      @Bean 
      public Docket createRestApi() { 
          //回到文本文档引言信息内容 
          return new Docket(DocumentationType.OAS_30) 
                  .apiInfo(apiInfo()) 
                  .select() 
                  .apis(RequestHandlerSelectors.withMethodAnnotation(Operation.class)) 
                  .paths(PathSelectors.any()) 
                  .build() 
                  .globalRequestParameters(getGlobalRequestParameters()) 
                  .globalResponses(HttpMethod.GET, getGlobalResponseMessage()) 
                  .globalResponses(HttpMethod.POST, getGlobalResponseMessage()); 
      } 
   
      /** 
       * 转化成插口信息内容，包含文章标题、手机联系人等 
       */ 
      private ApiInfo apiInfo() { 
          return new ApiInfoBuilder() 
                  .title("Swagger3api文档") 
                  .description("如有疑问，可联络二师兄，手机微信：zhuan2quan") 
                  .contact(new Contact("二师兄", "https://www.choupangxia.com/", "secbro2@gmail.com")) 
                  .version("1.0") 
                  .build(); 
      } 
   
      /** 
       * 封裝全局性通用性主要参数 
       */ 
      private List<RequestParameter> getGlobalRequestParameters() { 
          List<RequestParameter> parameters = new ArrayList<>(); 
          parameters.add(new RequestParameterBuilder() 
                  .name("uuid") 
                  .description("机器设备uuid") 
                  .required(true) 
                  .in(ParameterType.QUERY) 
                  .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING))) 
                  .required(false) 
                  .build()); 
          return parameters; 
      } 
   
      /** 
       * 封裝通用性回应信息内容 
       */ 
      private List<Response> getGlobalResponseMessage() { 
          List<Response> responseList = new ArrayList<>(); 
          responseList.add(new ResponseBuilder().code("404").description("找不到資源").build()); 
          return responseList; 
      } 
  }

根据之上配备早已完成了Spring Boot与Swagger的集成化，下边展现一下怎样在领域模型中开展应用。

业务流程中应用

建立2个dao层Goods(产品类)和CommonResult(通用性回到結果类)。

Goods类：

 
  @ApiModel("产品实体模型") 
  public class Goods { 
   
      /** 
       * 产品id 
       */ 
      @ApiModelProperty("产品ID") 
      Long goodsId; 
   
      /** 
       * 产品名称 
       */ 
      @ApiModelProperty("产品名称") 
      private String goodsName; 
   
      /** 
       * 产品价格 
       */ 
      @ApiModelProperty("产品价格") 
      private BigDecimal price; 
   
      // 省去getter/setter 
  }

CommonResult类：

 
  @ApiModel("API通用性数据信息") 
  public class CommonResult<T> { 
   
      /** 
       * 标志编码，0表明取得成功，非0表明打错 
       */ 
      @ApiModelProperty("标志编码,0表明取得成功，非0表明打错") 
      private Integer code; 
   
      /** 
       * 叙述信息内容，一般错时应用 
       */ 
      @ApiModelProperty("不正确叙述") 
      private String msg; 
   
      /** 
       * 业务流程数据信息 
       */ 
      @ApiModelProperty("业务流程数据信息") 
      private T data; 
   
      public CommonResult(Integer status, String msg, T data) { 
          this.code = status; 
          this.msg = msg; 
          this.data = data; 
      } 
   
      /** 
       * 取得成功 
       */ 
      public static <T> CommonResult<T> success(T data) { 
          return new CommonResult<>(0, "取得成功", data); 
      } 
   
      public static <T> CommonResult<T> success(Integer code, String msg) { 
          return new CommonResult<>(code, msg, null); 
      } 
   
      /** 
       * 不正确 
       */ 
      public static <T> CommonResult<T> error(int code, String msg) { 
          return new CommonResult<>(code, msg, null); 
      } 
   
      // 省去getter/setter 
  }

下边对于Controller层的插口来应用Swagger相匹配的API。

GoodsController类：

 
  @Api(tags = "产品信息化管理插口") 
  @RestController 
  @RequestMapping("/goods") 
  public class GoodsController { 
   
      @Operation(summary = "单独商品详情") 
      @GetMapping("/findGoodsById") 
      public CommonResult<Goods> findGoodsById( 
              @Parameter(description = "产品ID,正整数") 
              @RequestParam(value = "goodsId", required = false, defaultValue = "0") Integer goodsId) { 
          System.out.println("依据产品ID="   goodsId   "查看商品详情"); 
          Goods goods = new Goods(); 
          goods.setGoodsId(1L); 
          goods.setGoodsName("笔记本电脑"); 
          goods.setPrice(new BigDecimal(8888)); 
          return CommonResult.success(goods); 
      } 
  }

OrderController类：

 
  @Api(tags = "订单管理系统插口") 
  @RestController 
  @RequestMapping("/order") 
  public class OrderController { 
   
      @Operation(summary = "下单") 
      @PostMapping("/order") 
      @ApiImplicitParams({ 
              @ApiImplicitParam(name = "userId", value = "客户id", dataTypeClass = Long.class, paramType = "query", example = "123"), 
              @ApiImplicitParam(name = "goodsId", value = "产品id", dataTypeClass = Integer.class, paramType = "query", example = "1") 
      }) 
      public CommonResult<String> toBuy(@ApiIgnore @RequestParam Map<String, String> params) { 
          System.out.println(params); 
          return CommonResult.success("success"); 
      } 
  }

展现实际效果

进行集成化，运行SpringBoot新项目，在浏览详细地址：

http://127.0.0.1:8080/swagger-ui/index.html

从总体上能够见到以下实际效果：

实际的产品信息化管理插口，能够见到要求主要参数、回到結果算法设计等信息内容，点一下“Try it out”，可键入主要参数要求主要参数，开展插口的启用：

启用以后会回到相匹配的事件处理：

在最下边的Schemas中还能够见到相匹配回到結果数据信息和被Swagger注释的dao层信息内容。

Swagger3注释使用说明书

历经以上案例以后，我们知道大部分API是怎么使用的了，这了再归纳一下有关API的作用：

 
  @Api：用在要求的类上，表明对类的表明 
      tags="表明此类的功效，能够 在UI页面上见到的注释" 
      value="该主要参数没有什么实际意义，在UI页面上也见到，因此不用配备" 
   
  @ApiOperation：用在要求的方式 上，说明方法的主要用途、功效 
      value="说明方法的主要用途、功效" 
      notes="方式 的备注名称表明" 
   
  @ApiImplicitParams：用在要求的方式 上，表明一组主要参数表明 
      @ApiImplicitParam：用在@ApiImplicitParams注释中，特定一个要求主要参数的各个领域 
          name：主要参数名 
          value：主要参数的中国汉字表明、表述 
          required：主要参数是不是务必传 
          paramType：主要参数放在哪个地方 
              · header --> 要求主要参数的获得：@RequestHeader 
              · query --> 要求主要参数的获得：@RequestParam 
              · path（用以restful插口）--> 要求主要参数的获得：@PathVariable 
              · body（不常见） 
              · form（不常见）     
          dataType：主要参数种类，默认设置String，其他值dataType="Integer"        
          defaultValue：主要参数的初始值 
   
  @ApiResponses：用在要求的方式 上，表明一组回应 
      @ApiResponse：用在@ApiResponses中，一般用以表述一个不正确的回应信息内容 
          code：数据，比如400 
          message：信息内容，比如"要求主要参数没填好" 
          response：抛出异常的类 
   
  @ApiModel：用以回应类上，表明一个回到回应数据信息的信息内容 
              （这类一般用在post建立的情况下，应用@RequestBody那样的情景， 
              要求主要参数没法应用@ApiImplicitParam注释开展叙述的情况下） 
      @ApiModelProperty：用在特性上，叙述回应类的特性

集成化knife4j导出来线下文本文档

Swagger为大家出示了便捷的在线文档编辑适用，但一些情景下大家必须把api文档出示给协作工作人员，而不是立即给一个详细地址。这时，大家就必须将api文档导出来为线下文本文档。

这儿大家集成化提高文本文档knife4j来完成线下文本文档的导出来。

加上knife4j依靠

在pom.xml中提升knife4j的依靠：

 
  <dependency> 
      <groupId>com.github.xiaoymin</groupId> 
      <artifactId>knife4j-spring-boot-starter</artifactId> 
      <version>3.0.2</version> 
  </dependency>

运行knife4j

在上面配备Swagger的Swagger3Config中加上@EnableKnife4j注释，该注释能够打开knife4j的提高作用。

 
  @EnableKnife4j 
  @Configuration 
  @EnableOpenApi 
  public class Swagger3Config { 
      // ... 
  }

这时，假如依然浏览http://localhost:8080/swagger-ui/index.html会发觉表明并沒有转变。这儿大家必须浏览http://localhost:8088/doc.html。

全部新项目源代码详细地址：https://github.com/secbr/springboot-all/tree/master/springboot-swagger3。

展现实际效果

这时运行新项目，浏览doc.html以后，你能发觉如今文本文档设计风格越来越十分炫酷。展现好多个设计效果图讨论一下：

在其中在“线下文本文档”一栏中能够见到四种方式的线下文档下载：Markdown、HTML、Word、OpenAPI。

在其中我觉得HTML文件格式的文本文档更具备没敢，也更便捷查询，来一张图看一下实际效果。

总结

文本文档是新项目中务必的，但伴随着开源框架的发展趋势，对专业技术人员而言文本文档的困扰也在逐渐处理。假如你要处在笔写文本文档的环节，确实能够试着一下这种更友善的文本文档呈现方式。

the end

免责声明：本文不代表本站的观点和立场，如有侵权请联系本站删除！本站仅提供信息存储空间服务。

SpringBoot集成Swagger3，还想来份离线文档？真酷炫

序言

Swagger介绍

Swagger处理的困扰

Swagger3的更改

SpringBoot集成化Swagger3

Swagger3注释使用说明书

集成化knife4j导出来线下文本文档

总结

精选推荐

让 Flutter 在鸿蒙系统上跑起来

小冰一口气发布11个AI歌手：仅训练45天媲美专业级歌手

京东智能客服品牌焕新：“言犀”亮相2020京东JDD大会

AI改进建筑施工安全的十种方式

六项任务、多种数据类型，谷歌、DeepMind提出高效Transformer评估基准

第四范式NeurIPS 2020：知识图谱嵌入的自动化

随机推荐

SpringBoot集成Swagger3，还想来份离线文档？真酷炫

序言

Swagger介绍

Swagger处理的困扰

Swagger3的更改

SpringBoot集成化Swagger3

Swagger3注释使用说明书

集成化knife4j导出来线下文本文档

总结

精选推荐

让 Flutter 在鸿蒙系统上跑起来

小冰一口气发布11个AI歌手：仅训练45天 媲美专业级歌手

京东智能客服品牌焕新：“言犀”亮相2020京东JDD大会

AI改进建筑施工安全的十种方式

六项任务、多种数据类型，谷歌、DeepMind提出高效Transformer评估基准

第四范式NeurIPS 2020：知识图谱嵌入的自动化

随机推荐

小冰一口气发布11个AI歌手：仅训练45天媲美专业级歌手