SpringBoot整合Swagger2

1.简介

        Swagger是为了解决企业中接口（api）中定义统一标准规范的文档生成工具。于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档， 所以很多企业中都会有统一的规范文档，来定义接口标准。

        目前的项目基本都是前后端分离，后端为前端提供接口的同时，还需同时提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新，这个时候有可能会忘记更新接口的说明文档，造成一些不必要的问题。

2.如何使用接口文档swagger2

        2.1引入依赖

<!--swagger2依赖-->
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.9.1.RELEASE</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.7.8</version>
        </dependency>

2.2创建一个配置类-Swagger2

@Configuration
@EnableSwagger2//开启swagger注解驱动
public class SwaggerConfig {
    @Bean//把方法返回的数据对象 交于spring容器管理
    public Docket docket(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2).groupName("Chicken fame")
                .apiInfo(getInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yzl.controller"))//只为com.yzl.controller包下的类生成接口文档
                .build();
        return docket;
    }

    private ApiInfo getInfo(){
        Contact DEFAULT_CONTACT = new Contact("蔡徐坤", "https://www.qubiaoqing.cn/showinfo-1-183418-0.html", "15137602985@qq.com");
        ApiInfo apiInfo=new ApiInfo("一个真正的Man测试系统API", "一个真正的Man测试系统API", "1.6.0", "https://www.keaitupian.cn/biaoqingbao/19657.html",
                DEFAULT_CONTACT, "一个真正的Man", "http://www.cxk.com", new ArrayList<VendorExtension>());
        return apiInfo;
    }
}

2.3启动项目

        根据控制台提供的端口号访问localhost：端口号/doc.html

2.4swagger中常用的注解

六个注解：

• @Api：用在controller上，对controller进行注释；
• @ApiOperation：用在API方法上，对该API做注释，说明API的作用；
• @ApiImplicitParam：用在@ApiImplicitParams注解中，也可以单独使用，说明一个请求参数的各个方面，该注解包含的常用选项有：
• paramType：参数所放置的地方，包含query、header、path、body以及form，最常用的是前四个。
• name：参数名；
• dataType：参数类型，可以是基础数据类型，也可以是一个class；
• required：参数是否必须传；
• value：参数的注释，说明参数的意义；
• defaultValue：参数的默认值；
• @ApiModel:用于标注实体类
• @ApiModelProperty：用于实体类的属性说明

（2023年5月24日20:16:39 补充）

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

• paramType：参数放在哪个地方
• header-->请求参数的获取：@RequestHeader
• query-->请求参数的获取：@RequestParam
• path（用于restful接口）-->请求参数的获取：@PathVariable
• body（不常用）
• form（不常用）
• name：参数名
• dataType：参数类型
• required：参数是否必须传
• value：参数的意思
• defaultValue：参数的默认值

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

• code：数字，例如400
• message：信息，例如"请求参数没填好"
• response：抛出异常的类
• response = UserVo.class  这里UserVo是一个配置了@ApiModel注解的对像，该是对像属性已配置

@ApiModelProperty,swagger可以通过这些配置，生　成接口返回值