@swagger注解

一、前言

作为一个以前后端分离为模式开发小组，我们每隔一段时间都进行这样一个场景：前端人员和后端开发在一起热烈的讨论"哎,你这参数又变了啊",“接口怎么又请求不通了啊”,“你再试试,我打个断点调试一下…”。可以看到在前后端沟通中出现了不少问题。

对于这样的问题,之前一直没有很好的解决方案，直到它的出现，没错…这就是我们今天要讨论的神器:swagger,一款致力于解决接口规范化、标准化、文档化的开源库，一款真正的开发神器。(总结：就是让前端可以知道如何测试)

二、什么是@swagger

Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲，Swagger 就是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。（总结：接口的文档在线自动生成。）

三、SpringBoot引用@swagger

1、新建SpringBoot

2、编写swagger的配置文件

       <!--引入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>

3、开启swgger类

• 新建一个 SwaggerConfig 类

• 添加 @Configuration:表明这是一个配置类

• 开启 Swagger2

@Configuration  //表明这是一个注解类
@EnableSwagger2  //开启 Swagger2
public class SwaggerConfig {

}

注意:

如果报一下错误：

Failed to start bean ‘documentationPluginsBootstrapper‘； nested exception is java.lang.NullPointer

方法：在application.properties文件下添加此命令

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

3、访问

http://localhost:8080/swagger-ui.html

四、配置Swagger

1、配置基本信息

Swagger 有自己的实例 Docket，如果我们想要自定义基本信息，可以使用 docket 来配置 swagger 的基本信息，基本信息的设置在 ApiInfo 这个对象中。
在SwaggerConfig.java 配置文件添加以下内容：

    @Bean
    public Docket docket() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                // 配置基本信息
                .apiInfo(apiInfo());
    }

    // 基本信息设置
    private ApiInfo apiInfo() {
        Contact contact = new Contact(
                "程农", // 作者姓名
                "https://www.csdn.net/?spm=1001.2014.3001.4476", // 作者网址
                "307502005@qq.com"); // 作者邮箱
        return new ApiInfoBuilder()
                .title("多加辣-接口文档") // 标题
                .description("众里寻他千百度，慕然回首那人却在灯火阑珊处") // 描述
                .termsOfServiceUrl("https://www.baidu.com") // 跳转连接
                .version("1.0") // 版本
                .license("Swagger-的使用(详细教程)")
                .licenseUrl("https://blog.csdn.net/xhmico/article/details/125353535")
                .contact(contact)
                .build();
    }

重启服务，打开 Swagger 文档，基本信息改变如下所示：

2、配置接口信息

默认情况下，Swagger 是会展示所有的接口信息的，包括最基础的 basic-error 相关的接口

有时候我们希望不要展示 basic-error-controller 相关的接口，或者是说这想要显示某些接口，比如说：test包 下的接口，由该怎么去实现呢？这个时候就需要设置 扫描接口

    @Bean
    public Docket docket() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)

                // 配置接口信息
                .select() // 设置扫描接口
                // 配置如何扫描接口
                .apis(RequestHandlerSelectors
                        //.any() // 扫描全部的接口，默认
                        //.none() // 全部不扫描
                        .basePackage("com.example.demo.test") // 扫描指定包下的接口，最为常用
                        //.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口
                        //.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口

                )
                .paths(PathSelectors
                        .any() // 满足条件的路径，该断言总为true
                        //.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）
                        //.ant("/user/**") // 满足字符串表达式路径
                        //.regex("") // 符合正则的路径
                )
                .build();
    }

3、配置分组信息

Swagger 默认只有一个 default 分组选项，如果没有设置，所有的接口都会显示在 default `分组下，如果功能模块和接口数量一多，就会显得比较凌乱，不方便查找和使用。
swagger 文档中组名默认是 default，可通过 .groupName(String )

    @Bean
    public Docket docket() {
        // 创建一个 swagger 的 bean 实例
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("mike") // 修改组名为 "mike"
                ;
    }

五、常用注解

注解	作用	使用位置
@Api	表示对类的说明常用参数	类上面
@ApiOperation	说明方法的用途、作用	方法上面
@ApiModel	表示一个返回响应数据的信息	响应类
@ApiModelProperty	描述响应类的属性	属性
@ApiIgnore	忽略某个字段使之不显示在文档中	属性

1、@Api

@Api 注解用于标注一个Controller（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。

属性	描述
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

@RestController
@RequestMapping("/hello")
@Api(value="用户controller",tags={"用户操作接口"})
public class HelloWord {
    @RequestMapping("/helloword")
    public String helloWord(){
        return "helloword";
    }
}

 
}

2、@ApiOperation

用在请求的方法上，说明方法的用途、作用

参数	描述
value	说明方法的用途、作用
notes	方法的备注说明
tags	操作标签，非空时将覆盖value的值
response	响应类型（即返回对象）
responseContainer	声明包装的响应容器（返回对象类型）。有效值为 “List”, “Set” or “Map”。
responseReference	指定对响应类型的引用。将覆盖任何指定的response（）类
httpMethod	指定HTTP方法，“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
responseHeaders	响应头列表
code	响应的HTTP状态代码。默认 200
hidden	默认为false， 配置为true 将在文档中隐藏

@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
    public String helloWord(){
        return "helloword";
    }

@ApiModel

用于响应类上，表示一个返回响应数据的信息

@ApiModel(value="用户登录信息", description="用于判断用户是否存在")
public class UserModel implements Serializable{
}

@ApiModelProperty

用在属性上，描述响应类的属性

参数	描述
value	此属性的简要说明。
name	允许覆盖属性名称
allowableValues	限制参数的可接受值。1.以逗号分隔的列表 2、范围值 3、设置最小值/最大值
access	允许从API文档中过滤属性。
notes	目前尚未使用。
dataType	参数的数据类型。可以是类名或者参数名，会覆盖类的属性名称。
required	参数是否必传，默认为false
position	允许在类中对属性进行排序。默认为0
hidden	允许在Swagger模型定义中隐藏该属性。
example	属性的示例。
readOnly	将属性设置为只读
reference	指定对相应类型定义的引用，覆盖指定的任何参数值

@ApiModel(value="用户登录信息", description="用于判断用户是否存在")
public class UserModel implements Serializable{

private static final long serialVersionUID = 1L;

/**

* 用户名

*/

@ApiModelProperty(value="用户名")

private String account;

/**

* 密码

*/

@ApiModelProperty(value="密码")

private String password;

}

@ApiIgnore 忽略某个属性，

使之不显示在swagger文档中显示

@GetMapping(value ="page")
@ApiOperation(value ="分页查询登录⽇志")
public Result page(@ApiIgnore LogVo vo){
	return null;
}