Swagger2

Swagger2

Swagger 是一套围绪 Open API 规范构建的开源工具，可以帮助设计，构建，记录和使用REST API。动态生成接口文档，方便前后端工作人员交流。

Open API规范描述:

• 每个访问地址的类型。
• 每个操作的参数。包括输入输出参数。
• 认证方法。
• 连接信息，声明，使用团队和其他信息。

依赖坐标

<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>

Springfox

Springfox 把 Swagger2 封装起来，把Swagger所需要的技术引入到当前框架内，而且提供注解开发和切面编程，可以让我们快速的进行开发

---

Docket 配置接口文档的描述信息和规则

package com.eirapplets.config;

import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;

/**
 * @author pangjian
 * @ClassName SwaggerConfig
 * @Description 接口文档配置类
 * @date 2021/4/15 13:50
 */

@Configuration
@EnableSwagger2
public class SwaggerConfig {


    /**
     * @Description: 创建Docke类型的对象，并交给spring容器托管，Docket是Swagger中的全局配置对象
     * @return springfox.documentation.spring.web.plugins.Docket
     * @date 2021/4/15 13:55
    */
    @Bean
    public Docket docket(){
        // 创建哪一个版本的全局配置对象，这里创建的是SWAGGER2的全局配置对象
        Docket docket = new Docket(DocumentationType.SWAGGER_2);

        // API帮助文档的描述信息对象
        ApiInfo apiInfo =
            new ApiInfoBuilder()
                .contact(
                        new Contact(
                                "软件工程12组-庞坚", // 发布的作者
                                "null",// 发布企业的网站
                                "614039502@qq.com"// 发布者的电子邮箱
                        )
                )
                .title("疫情信息上报系统接口文档") // 接口文档标题
                .description("用来疫情信息上报系统前后端开发人员接口交互的的文档") // 接口文档描述
                .version("1.0") // 接口文档版本号
                .build();

        // 给docket上下文配置api描述信息
        docket.apiInfo(apiInfo);

        // 构建规则
        docket
                .select() // 获取Docket中的选择器。返回 ApiSelectorBuilder。构建选择器
                .apis(
                        Predicates.not( // 取反 true->false，API文档不会有这个接口的描述信息，过滤掉
                                RequestHandlerSelectors.withMethodAnnotation( // 方法上有MySwaggerAnnotation注解返回true
                                        MySwaggerAnnotation.class // 自定义的注解
                                )
                        )
                )
                .paths(PathSelectors.regex("/*")) // 正则匹配扫描路径
                .apis(RequestHandlerSelectors.basePackage("com.eirapplets.controller")) // 设定扫描哪个包（包含子包）
                .build();

        return docket.groupName("庞坚");
    }


}

---

Swagger2 内置注解

@EnableSwagger2

@EnableSwagger2 是 springfox 提供的一个注解，代表swagger2相关技术开启。会扫描当前类所在包，及子包中所有的类型中的注解，做swagger文档的定值。

@Apilgnore

忽略，当前注解描述的方法或类型，不生成 api 帮助文档。

@Api(tags = “用户控制器”)

用于控制器类上，tags参数是给控制器类起一个别名

@ApiOperation(value = “登录方法”,notes = “处理post类型登录请求方法”)

用于控制器方法上，value参数必须提供，value参数是给控制器方法提供描述，notes参数是提供笔记，进一步说明

@ApiParam(name = “二维码”,value = “用户注册时填写的二维码”,required = true)

用于控制器方法参数上，name参数是参数别名，value是参数描述，required是参数是否是必须的，默认为false是不必需。

@ApiModel(value = “用户实体类”,description = “登录注册传输对象类”)

描述一个实体类，value是起别名，description是描述实体类

@ApiModelProperty(value = “主键”,name = “id”,required = false,example = “1”,hidden = false)

value参数是给属性一个描述信息，name参数是起别名，required参数表示必不必要，example参数是给属性一个示例，hidden参数表示属性是否是隐藏的

package com.eirapplets.pojo;


import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.experimental.Accessors;

/**
 * @author pangjian
 * @ClassName User
 * @Description 用户实体类
 * @date 2021/3/14 11:27
 */
@ApiModel(value = "用户实体类",description = "登录注册传输对象类")
@Data
@Accessors(chain = true)
public class User {

    @ApiModelProperty(value = "主键，由数据库自动生成",name = "id",required = false,example = "1",hidden = true)
    private int id;

    @ApiModelProperty(value = "姓名",name = "姓名(name)",required = true,example = "庞坚",hidden = false)
    private String name;

    @ApiModelProperty(value = "年级",name = "年级(grade)",required = true,example = "18003003",hidden = false)
    private String grade;

    @ApiModelProperty(value = "登录注册时提供登录对象密码属性",name = "密码(password)",required = true,example = "7758258",hidden = true)
    private String password;

    @ApiModelProperty(value = "学号",name = "学号(username)",required = true,example = "1800300425",hidden = false)
    private String username;

    @ApiModelProperty(value = "电话号码",name = "电话号码(phone)",required = true,example = "17607750063",hidden = true)
    private String phone;


}