2024.5.31 Friday
接上文【WEEK14】 【DAY4】Swagger第二部分【中文版】

16.6.配置API分组

16.6.1.修改SwaggerConfig.java

package com.P47.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;import java.util.ArrayList;@Configuration  //等价于@Component
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {//配置了Swagger的bean实例Docket，以配置Swagger的具体参数@Beanpublic Docket docket(Environment environment){// 设置要显示swagger的环境Profiles profiles = Profiles.of("dev", "test");// 判断当前是否处于该环境// 通过 enable() 接收此参数判断是否要显示boolean flag = environment.acceptsProfiles(profiles);flag=true;  //为了通过8080端口访问，又因为dev和test配置文件对应的端口不包含8080，所以为了让enable(flag)正常启动，只能手动给flag赋值return new Docket(DocumentationType.SWAGGER_2)  //源码见DocumentationType.classpublic class DocumentationType extends SimplePluginMetadata方法，选择符合当前版本的进行编辑.apiInfo(apiInfo()) //public Docket(DocumentationType documentationType)方法点开ApiInfo进入ApiInfo.class.enable(flag)  //是否启动swagger，false则不能启动，此时访问页面显示：😱 Could not render e, see the console..groupName("ZzzZzzzZzzzz-") //将原本的默认分组命名为自定义的名字.select()   //通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口//.apis(RequestHandlerSelectors.basePackage("com.P47.controll"))  //使用basePackage指定要扫描的包//.paths(PathSelectors.ant("/P47/**"))    //点击path查看初始化private Predicate<String> pathSelector; 这里以.ant()方法为例，只扫描请求以/P47开头的接口.build();}
//    配置多个分组，在页面中访问这些分组时页面是默认的页面设置：因为没有做其他配置@Beanpublic Docket docket1(){return new Docket(DocumentationType.SWAGGER_2).groupName("group1");}@Beanpublic Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName("group2");}@Beanpublic Docket docket3(){return new Docket(DocumentationType.SWAGGER_2).groupName("group3");}//配置Swagger信息（apiInfo）......
}

16.6.2.重启

分别选择group1，group2，group3

16.7.实体配置

16.7.1.新建pojo文件夹

新建User.java

@ApiModel为类添加注释
@ApiModelProperty为类属性添加注释

package com.P47.pojo;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;@ApiModel("用户实体")
public class User {@ApiModelProperty("用户名")public String username;@ApiModelProperty("密码")public String password;
}

16.7.2.修改HelloController.java

package com.P47.controller;import com.P47.pojo.User;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
public class HelloController {@RequestMapping(value = "/hello")public String hello(){return "hello";}@RequestMapping("/getUser")public User getUser(){return new User();  //刚才创建的User.java在getUser请求接口的返回值中，所以能够映射到实体项中（可以显示在页面中Models处）}
}

只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中
注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

16.7.3.重启

16.8.常用注解

16.8.1.Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

16.8.2.我们也可以给请求的接口配置一些注释（修改HelloController.java）

package com.P47.controller;import com.P47.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;@Api(tags = "对HelloController的文字解释")
@RestController
public class HelloController {@GetMapping(value = "/hello")   //从RequestMapping改来的public String hello(){return "hello";}@PostMapping("/getUser")    //从RequestMapping改来的public User getUser(){return new User();  //刚才创建的User.java在getUser请求接口的返回值中，所以能够映射到实体项中（可以显示在页面中Models处）}@ApiOperation("接口的注解")@PostMapping("/trytry")@ResponseBodypublic String Zzz(@ApiParam("被返回的名字注解写在这里")String usernameaa){return usernameaa;}
}

16.8.3.重启

可以点击右上角的“try it out”进行测试。
如：


优势：可以给一些比较难理解的属性或者接口，增加一些配置信息，让人更容易阅读！
相较于传统的Postman或Curl方式测试接口，使用swagger简直就是傻瓜式操作，不需要额外说明文档(写得好本身就是文档)而且更不容易出错，只需要录入数据然后点击Execute，如果再配合自动化框架，可以说基本就不需要人为操作了。
Swagger是个优秀的工具，现在国内已经有很多的中小型互联网公司都在使用它，相较于传统的要先出Word接口文档再测试的方式，显然这样也更符合现在的快速迭代开发行情。当然了，在正式环境要记得关闭Swagger，一来出于安全考虑，二来也可以节省运行时内存。