SpringBoot整合Swagger3--提效神器

老生常谈之学习知识三部曲--是什么？能干什么？怎么用？本文使用结合自己的理解将介绍swagger3以及使用springboot进行整合。拿去~

前言

前后端分离的项目，接口文档的存在十分重要。手动编写文档的效率太低

是什么？

• 是一个规范且完整的框架，用于生成、描述、调用和可视化 Restful 风格的 Web 服务。
• 是一个自动生成接口文档的工具，且与swagger2相比新版的swagger3配置更少，使用更加方便
• 是一款Restful 接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具
• 了解Swagger3与swagger2比较的变动
  • 删除了对springfox-swagger2的依赖；
  • 删除所有@EnableSwagger2...注解同时兼容；
  • 添加了springfox-boot-starter依赖项；
  • 移除了guava等第三方依赖；
  • 文档访问地址改为http://ip:port/project/swagger-ui/index.html。

能干什么？

• 目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步
• 及时性 ：接口变更后，前后端人员可实时看到最新版本
• 规范性 ：接口具体统一风格，如接口地址，请求方式，参数，响应格式和错误信息等
• 一致性 ：接口信息一致，不会因接口文档版本问题出现分歧
• 可测性 ：可直接基于接口文档进行在线测试

怎么干？

• 第一步：在pom文件中引入相关依赖

 

• 第二步：添加配置类SwaggerConfig

 

• 第三步：(可选)在配置文件中配置当前环境是否开启swagger

 

• 第四步：启动服务并访问http://自己服务的IP:服务的端口/swagger-ui/index.html

 

• 第五步：根据需求在各类中加上对应注解

  • @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：参数的默认值

    • 举例：

      

       

  • @ApiResponse：用在请求的方法上，表示一组响应

    • 用在@ApiResponses中，一般用于表达一个错误的响应信息

    • code：数字，例如400

    • message：信息，例如"请求参数没填好"

    • response：抛出异常的类

    • 举例：

      

       

  • @ApiModel：用于响应类上，表示一个返回响应数据的信息。（这种一般用在post创建的时候，使用@RequestBody这样的场景， 请求参数无法使用@ApiImplicitParam注解进行描述的时候）

    • @ApiModelProperty：用在属性上，描述响应类的属性

      • 举例：

        

    • 举例：

       

      

       

  • @ApiParam 用于 Controller 中方法的参数说明

    • value：参数说明

    • required：是否必填

    • 举例：

      

       

• 第六步（可选）：如果有导出离线文档的需求需要额外多做几步

  • 6.1 : 添加knife4j依赖

 

• 6.2：在swagger配置类中加上注解@EnableKnife4j

  

• 6.3：重启项目访问 http://ip:port/doc.html

  

• 6.4 : 在 页面‘文档管理’--->‘离线文档’页面可进行下载。支持Markdown、HTML、Word、OpenAPI四种格式。

  

感谢耐心的你~后面会补充接入swagger会出现的常见问题~