Swagger介绍

导语

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。

Swagger是什么？它能干什么？

发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。
但即便如此，对于许多开发来说，编写这个yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。

介绍

Swagger是一个接口文档生成工具，同时提供接口测试调用的辅助功能。

关于 Swagger

Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：
mSwagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
Swagger 有一个强大的社区，里面有许多强悍的贡献者。
Swagger 文档提供了一个方法，使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API，包括了比如 names、order 等 API 信息。
你可以通过一个文本编辑器来编辑 Swagger 文件，或者你也可以从你的代码注释中自动生成。各种工具都可以使用 Swagger 文件来生成互动的 API 文档。
注意：用 Swagger 文件生成互动的 API 文档是最精简的，它展示了资源、参数、请求、响应。但是它不会提供你的API如何工作的其他任何一个细节。

swagger调式技巧

  • 本文主要介绍本项目采用Swagger方式
    • 通过网关访问Swagger，该Swagger会把聚合后的文档进行访问需要配置哪些参数
    • 访问单个服务时，需要配置哪些参数
    • 枚举如何传递参数（@RequestParam @RequestBody）
    • LocalDateTime、LocalDate、LocalTime、 Date类型如何传递（@RequestParam @RequestBody）

以下是采用knife4j2.0.8版本进行封装成start，通过yml文件配置，自动创建docket案例，省去了每次项目引用都要去创建config类并去手动创建docket

  • knife4j-sjk-springboot-autoconfiguration和nife4j-sjk-springboot-start
    已经封装成star进行自动装配，通过在yml配置，自动创建docket和分组docket;yml配置如下
# knife4j 全局配置, 参考knife4j官方文档
   knife4j:
     enable: true
     setting:
       enableReloadCacheParameter: true
       enableVersion: true
       enableDynamicParameter: true
       enableFooter: false
       enableFooterCustom: true
       footerCustomContent: Apache License 2.0 | Copyright 2020 [百度](http://baidu.com)
  • knife4j 提供了生产环境禁用、访问密码、修改文档基础样式等功能, 更多功能参考: knife4j
  • SwaggerProperties 提供了动态配置docket文档的能力, 修改 lamp-xxx-server.yml 配置文件配置多个文档group.
sjk:
  swagger:
    docket:
      auth:
        title: xxx模块接口
        base-package: com.knife4j.sjk.demo.controller
      common:
        title: 公共模块
        base-package: com.knife4j.sjk.demo.controller

knife4j-sjk-start-demo是引用start一个demo例子，具体demo源码详细地址见
github demo源码

参考地址:
https://www.cnblogs.com/shihaiming/p/12343314.html
https://gitee.com/xiaoym/knife4j

开源仓库

Github
https://github.com/xiaoymin/swagger-bootstrap-ui
码云
https://gitee.com/xiaoym/knife4j

Demo
https://gitee.com/xiaoym/swagger-bootstrap-ui-demo

【推广】 免费学中医，健康全家人
原文地址：https://www.cnblogs.com/sjkzy/p/14309739.html