SpringBoot集成swagger

说到swagger（丝袜哥），首先了解一下OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程，目前版本是V3.0，并且已经发布并开源在github上。（https://github.com/OAI/OpenAPI-Specification）；

swagger是目前最受欢迎的OpenAPI规范（OAS）开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发；

wagger官网：https://swagger.io/ 是一个开源项目，也就是提供jar包)；

swagger2 版本：1.x，2.x，现在都用2.x；

Spring Boot也集成了swagger，可以很方便地在springboot中使用swagger生成api接口文档；

swagger的作用：

随项目自动生成强大RESTful API文档，减少开发人员工作量；（不需要自己写api接口文档了），使用swagger，只需要在代码中添加一些注解即可生成API接口文档，便于同步更新API文档的说明，当然也有人诟病说这种方式与代码耦合在一起，智者见智仁者见仁；

另外生成的api文档页面带有测试功能，可以用来调试每个RESTful API接口；

怎么集成？

springboot集成第三方组件一般情况下是三个步骤：

1、加依赖（可能是starter）；

2、配置application.properties文件；

3、写代码；

所以：

1、添加相关依赖

1、配置文件（暂时不需要在application.properties配置）

2、编写相关代码，需要用到一些注解；

标红色的这些都是swagger的注解；

然后在spring ioc容器中配置创建一个Docket对象；

具体参考课堂上的样例代码；

完成后访问：http://localhost:8080/swagger-ui.html 得到API文档；（如果有项目上下文地址要带上项目上下文）

说明：2.10.5 这个版本目前使用的时候有点问题，后续再看一下；

接口api的数据查看：http://localhost:8080/24-springboot/v2/api-docs

swagger常用注解：

• @Api：用在类上，说明该类的作用；

• @ApiOperation：用在方法上，说明方法的作用；

• @ApiImplicitParams：用在方法上包含一组参数说明；

• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面：

• paramType：参数放在哪个地方；

• header-->请求参数的获取：@RequestHeader；

• query-->请求参数的获取：@RequestParam；

• path-->请求参数的获取：@PathVariable （用于restful接口）；

• body（不常用）；

• form（不常用）；

• name： 参数名；

• dataType：参数类型；

• required：参数是否必须传；

• value：参数的意思；

• defaultValue：参数的默认值；

• @ApiResponses：用于表示一组响应；

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

• code：数字，例如400；

• message：信息，例如 "请求参数不合法"；

• response：抛出异常的类；

• @ApiIgnore：使用该注解忽略这个API，在页面上不显示；

• @ApiModel：描述一个Model的信息；

• @ApiModelProperty：描述一个model的属性；

注解可参考官方：https://github.com/swagger-api/swagger-core/wiki/Annotations 

WebJars是将Web前端Javascript和CSS等资源打包成Java的Jar包,这样在Java Web开发中我们可以借助Maven这些依赖库的管理,保证这些Web资源版本唯一性；

swagger安全性问题: 正式上线的时候，建议关闭swagger；

在配置文件配置一个开关：开启或关闭：

springfox与swagger的关系

swagger是一个流行的API开发框架，这个框架实现了“开放API声明”（OpenAPI Specification，OAS）规范；

由于Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来，而springfox则是从swagger-springmvc这个组件发展而来，同时springfox也是一个新的

项目，目前新的项目中都是使用springfox-swagger2，其实在一些比较老的项目中可能还会用swagger-springmvc；

springfox-swagger2依然是实现OSA规范，生成一个描述API的json文件，，另外一个组件springfox-swagger-ui就是将这个json文件解析出来，用一种更友好的页面效果方式呈现出来；

Lombok介绍

lombok就是一个jar包，加到项目中；

使用lombok的步骤如下：

1、加入lombok的依赖；

<!--lombok-->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.12</version>
</dependency>

2、Idea工具需要改一个配置；

3、写代码的时候，在代码上加一些lombok的注解；常用的注解：

@NoArgsConstructor
@Getter
@Setter
@Data

如果想更深入的学习springboot，奉上springboot全套视频教程，视频学习效果更佳，走过路过别忘素质三连哦~~