接口组可以使用@Api来划分

• value：字段说明
• example：设置请求示例（Example Value）的默认值，如果不配置，当字段为string的时候，此时请求示例中默认值为"".
• name：用新的字段名来替代旧的字段名。而swagger就是一个在你写接口的时候自动帮你生成接口文档的东西，只要你遵循它的规范并写一些接口的说明注解即可。
• 没有接口文档更新管理，虽然一个接口更新之后，可能不会关心旧版的接口信息，但你“可能”想看看旧版的接口信息，例如有些灰度更新发布的时候可能还会关心旧版的接口。

  UI对比：

  
  

  使用

  1.添加依赖包：

  <!--引入swagger--><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency><!-- 引入swagger-bootstrap-ui依赖包--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.8.7</version></dependency>

  2.在swagger配置类中增加注解@EnableSwaggerBootstrapUI:

  @Configuration// 标明是配置类@EnableSwagger2//开启swagger功能@EnableSwaggerBootstrapUI// 开启SwaggerBootstrapUIpublicclassSwaggerConfig{// 省略配置内容}

  3.访问API：http://localhost:8080/doc.html，即可预览到基于bootstarp的Swagger UI界面。
  【如果你的接口是form-data,x-www-form-urlencoded的时候可能不能使用swagger页面API调试，但可以在后面讲到基于BootstrapUI的swagger增强中调试，基于BootstrapUI的swagger支持指定form-data或x-www-form-urlencoded】

示例一：声明入参是URL参数

// 使用URL query参数@ApiOperation(value ="登录接口2",notes ="登录接口的说明2")@ApiImplicitParams({@ApiImplicitParam(name ="username",//参数名字value ="用户名",//参数的描述required =true,//是否必须传入//paramType定义参数传递类型：有path,query,body,form,headerparamType ="query"),@ApiImplicitParam(name ="password",//参数名字value ="密码",//参数的描述required =true,//是否必须传入paramType ="query")})@PostMapping(value ="/login2")publicLoginFormlogin2(Stringusername,Stringpassword){System.out.println(username+":"+password);LoginFormloginForm =newLoginForm();loginForm.setUsername(username);loginForm.setPassword(password);returnloginForm;}

示例二：声明入参是URL路径参数

// 使用路径参数@PostMapping("/login3/{id1}/{id2}")@ApiOperation(value ="登录接口3",notes ="登录接口的说明3")@ApiImplicitParams({@ApiImplicitParam(name ="id1",//参数名字value ="用户名",//参数的描述required =true,//是否必须传入//paramType定义参数传递类型：有path,query,body,form,headerparamType ="path"),@ApiImplicitParam(name ="id2",//参数名字value ="密码",//参数的描述required =true,//是否必须传入paramType ="path")})publicStringlogin3(@PathVariableIntegerid1,@PathVariableIntegerid2){returnid1+":"+id2;}

示例三：声明入参是header参数

// 用header传递参数@PostMapping("/login4")@ApiOperation(value ="登录接口4",notes ="登录接口的说明4")@ApiImplicitParams({@ApiImplicitParam(name ="username",//参数名字value ="用户名",//参数的描述required =true,//是否必须传入//paramType定义参数传递类型：有path,query,body,form,headerparamType ="header"),@ApiImplicitParam(name ="password",//参数名字value ="密码",//参数的描述required =true,//是否必须传入paramType ="header")})publicStringlogin4(@RequestHeaderStringusername,@RequestHeaderStringpassword){returnusername+":"+password;}

示例四：声明文件上传参数

// 有文件上传时要用@ApiParam，用法基本与@ApiImplicitParam一样，不过@ApiParam用在参数上// 或者你也可以不注解，swagger会自动生成说明@ApiOperation(value ="上传文件",notes ="上传文件")@PostMapping(value ="/upload")publicStringupload(@ApiParam(value ="图片文件",required =true)MultipartFileuploadFile){StringoriginalFilename =uploadFile.getOriginalFilename();returnoriginalFilename;}// 多个文件上传时，**swagger只能测试单文件上传**@ApiOperation(value ="上传多个文件",notes ="上传多个文件")@PostMapping(value ="/upload2",consumes ="multipart/*",headers ="content-type=multipart/form-data")publicStringupload2(@ApiParam(value ="图片文件",required =true,allowMultiple =true)MultipartFile[]uploadFile){StringBuffersb =newStringBuffer();for(inti =0;i <uploadFile.length;i++){System.out.println(uploadFile[i].getOriginalFilename());sb.append(uploadFile[i].getOriginalFilename());sb.append(",");}returnsb.toString();}// 既有文件，又有参数@ApiOperation(value ="既有文件，又有参数",notes ="既有文件，又有参数")@PostMapping(value ="/upload3")@ApiImplicitParams({@ApiImplicitParam(name ="name",value ="图片新名字",required =true)})publicStringupload3(@ApiParam(value ="图片文件",required =true)MultipartFileuploadFile,Stringname){StringoriginalFilename =uploadFile.getOriginalFilename();returnoriginalFilename+":"+name;}~~~## 定义接口响应### 响应是实体类：前面在定义接口请求参数的时候有提到使用`@ApiModel`来标注类，如果接口返回了这个类，那么这个类上的说明也会作为响应的说明：```java    // 返回被@ApiModel标注的类对象@ApiOperation(value ="实体类响应",notes ="返回数据为实体类的接口")@PostMapping("/role1")publicLoginFormrole1(@RequestBodyLoginFormloginForm){returnloginForm;}

响应是非实体类：

swagger无法对非实体类的响应进行详细说明，只能标注响应码等信息。
然后在Spring Boot配置文件中修改当前profilespring.profiles.active=release，重启之后，此时无法访问http://localhost:8080/swagger-ui.html

Swagger3.0与Swagger2对比

想到swagger3已经更新了，于是想着尝鲜使用下，的确省去了很多配置。@RestControllerpublicclassUserController{}

🔵你也可以理解成基于tags来分组，就好像一些文章里面的标签一样，使用标签来分类。@RestControllerpublicclassRoleController{}

和

@Api(tags ="用户管理")//  tags：你可以当作是这个组的名字。
🔵如果这个Controller下（接口组）下面没有接口，那么在swagger ui中是不会显示的，如果有的话就会这样显示：
定义接口
使用了@Api来标注一个Controller之后，如果下面有接口，那么就会默认生成文档，但没有我们自定义的说明：
@Api(tags ="用户管理")@RestControllerpublicclassUserController{// 注意，对于swagger，不要使用@RequestMapping，// 因为@RequestMapping支持任意请求方式，swagger会为这个接口生成7种请求方式的接口文档@GetMapping("/info")publicStringinfo(Stringid){return"aaa";}}


我们可以使用@ApiOperation来描述接口，比如：
@ApiOperation(value ="用户测试",notes ="用户测试notes")@GetMapping("/test")publicStringtest(Stringid){return"test";}
常用配置项：
value：可以当作是接口的简称
notes：接口的描述
tags：可以额外定义接口组，比如这个接口外层已经有@Api(tags = “用户管理”)，将接口划分到了“用户管理”中，但你可以额外的使用tags，例如tags = "角色管理"让角色管理中也有这个接口文档。这样就不会发送我修改了接口，却忘记更新接口文档的情况。
支持在线调试，swagger提供了在线调用接口的功能。
1.添加依赖包：
❗注意，这里的前提是已经导入了spring boot的web包。（当然了，这个问题等你会swagger之后你就大概就会怎么规避这个问题了。springfox-swagger-uispringfox-boot-starter启用方式@EnableSwagger2@EnableOpenApi访问方式ip:port/swagger-ui.htmlip:port/swagger-ui/index.htmlDoucument类型DocumentationType.SWAGGER_2DocumentationType.OAS_30
使用流程
1.导入Maven坐标
优化：openapi3依赖添加，现在非常方便，不像以往2.9.2版本需要好几个依赖，现在只需添加一个
io.springfox springfox-boot-starter 3.0.0
2.配置
推荐配置文件和代码分离
注解的更改：由之前的@Swagger2更改为@EnableOpenApi
Docket构造函数中的DocumentationType指向更改：由之前的DocumentationType.SWAGGER_2更改为DocumentationType.OAS_30
对于扫描路径部分可以自行选择（当项目人多的时候可以自由扩展，人少就自行安排）
paths(PathSelectors.regex(“asds”)
.or(PathSelectors.regex(“adsd”))
.or(…)
)
此外还具备swagger进行授权配置，在开发环境的基础上进一步封装
@PropertySource(value ={"classpath:/config/Swagger3.properties"})@EnableOpenApi@ConfigurationpublicclassSwagger3Config{/**	对应的配置文件信息		* 是否开启swagger，开发环境打开，线上关闭	* nature.restApi.enabled=true		* 项目名称	* application.name=SecKill-应用服务API		* 项目版本信息	* application.version=1.0		* 项目描述信息	* application.description=秒杀-API接口文档		* 分组信息(可自行添加)	* application.group01=lyh		* 扫描路径选择	application.apis.selector=com.gan.springseckill.controller	*/@Value("${nature.restApi.enabled}")privateBooleanenable;@Value("${application.name}")privateStringapplicationName;@Value("${application.version}")privateStringapplicationVersion;@Value("${application.description}")privateStringapplicationDescription;@Value("${application.group01}")privateStringapplicationGroup01;@Value("${application.apis.selector}")privateStringselector;@BeanpublicDocketdocket(){returnnewDocket(DocumentationType.OAS_30).apiInfo(apiInfo()).groupName(applicationGroup01).select().apis(RequestHandlerSelectors.basePackage(selector)).paths(PathSelectors.any()).build();}privateApiInfoapiInfo(){returnnewApiInfoBuilder().title(applicationName).description(applicationDescription).version(applicationVersion).build();}}