SpringBoot整合SSE demo springboot整合swagger3

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

前言

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

是什么？

• 是一个规范且完整的框架，用于生成、描述、调用和可视化 Restful 风格的 Web 服务。
• 是一个自动生成接口文档的工具，且与swagger2相比新版的swagger3配置更少，使用更加方便
• 是一款Restful 接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具
• 了解Swagger3与swagger2比较的变动

• 删除了对springfox-swagger2的依赖；
• 删除所有@EnableSwagger2...注解同时兼容；
• 添加了springfox-boot-starter依赖项；
• 移除了guava等第三方依赖；

能干什么？

• 目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许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会出现的常见问题~