Spring Boot 整合——swagger2使用

引入swagger配置

如今的开发，前后端分离越来越普遍。日常我们工作的时候前后端配合的时候，后端通常需要提供一份方便前端使用的API文档。而一篇文档的准确、可理解性的好坏是保证合作能否稳步进行的关键。而Swagger就是一种可以根据我们在代码中的注释来自动生成在线API文档的工具。有了Swagger不仅节省了大量编写API文档的时间，而且提供了调试的渠道。

依赖引入

使用swagger我们需要引入一个swagger核心组件以及与其配套的一个UI组件

<!-- 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启动的Docket环境。以及swagger的文档信息。

@Configuration
public class SwaggerConfig {

    /**
     * 创建swagger运行的docket环境
     * @return
     */
    @Bean
    public Docket createRestApi() {
        // 使用Docket启动，
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 扫描基础包
                .apis(RequestHandlerSelectors.basePackage("dai.samples.swagger"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建swagger的api信息
     * @return
     */
    private ApiInfo apiInfo() {
        // 配置名称地址和email
        Contact contact = new Contact("大·风","https://blog.csdn.net/qq330983778","email");
        return new ApiInfoBuilder()
                // 标题
                .title("Spring Boot 整合Swagger")
                // 描述
                .description("这个一个demo项目")
                .termsOfServiceUrl("https://blog.csdn.net/qq330983778")
                .version("1.0")
                .contact(contact)
                .build();
    }
    
    
}

然后我们在启动类上添加@EnableSwagger2注解

@EnableSwagger2
@SpringBootApplication
public class SwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

请求地址

此时我们请求：http://localhost:8000/swagger-ui.html。会进入swagger页面

因为此时我们只设置了一个简单的controller所以只会显示一个接口默认的文档格式

@Api
@RestController
@RequestMapping("BaseSwagger")
public class BaseSwaggerController {

    /**
     * 一个基础的测试
     * @param request
     * @return
     */
    @ApiOperation(value="测试基础对象")
    @RequestMapping(value = "base",method = RequestMethod.POST)
    public String base(ServletRequest request) {
        String contentType = request.getContentType();
        return "contentType：" + contentType;
    }
}

swagger使用场景

上面是一个非常基础，根据默认逻辑生成的文档格式。下面我们介绍下我们想实现更多自己的业务逻辑时候的参数设置

controller上的注解

假如我们想给Controller添加更多的信息的时候可以设置这些内容

@Api(value = "控制器类型",
        tags = "测试控制器类型注解内容")
@RestController
@RequestMapping("class")
public class TestClassAnnotationsController {

    /**
     * 一个基础的测试
     * @param request
     * @return
     */
    @ApiOperation(value="测试基础对象", notes="测试基础对象备注",httpMethod = "POST")
    @RequestMapping(value = "base",method = RequestMethod.POST)
    public String base(ServletRequest request) {
        String contentType = request.getContentType();
        return "contentType：" + contentType;
    }

}

此时API文档上不再像上面例子一样显示类名称的样式，而是会显示tags中的内容。

请求参数添加注解

当然除了增加堆controller的描述，我们可以增加对具体请求的信息描述

基础类型

假如我们传入的参数是分开的数据而非一个对象的时候，我们可以这样补充其信息

 /**
     * 测试请求参数添加描述
     * @param name
     * @param age
     * @return
     */
    @ApiOperation(value="参数请求(请求描述)", 
            notes="请求的注释(注释)",
            httpMethod = "POST",
            response = String.class
            )
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",value = "name的描述",defaultValue = "默认值",
                    dataTypeClass = String.class,paramType = "query",
                    example = "参数实例值"),
            @ApiImplicitParam(name = "age",value = "age的描述",allowableValues = "1,2,3",
                    dataTypeClass = Integer.class,paramType = "query")
    })
    @RequestMapping(value = "base",method = RequestMethod.POST)
    public String testBaseParams(String name,Integer age) {
        log.info("传入参数:name:{},age:{}",name,age);
        return "传入参数:name:"+name+",age:"+age;
    }

我们在上面添加了这些内容，
在方法上，首先我们提供了接口的作用value，而notes作为详细描述，然后我们声明了请求方法类别。
在参数上我们生命了参数的描述，设置了默认值，参数的类型，以及参数传递类别。同时声明了默认值

可以看到针对这个方法每个参数作用到文档中的样子。

而我们点击Try it out的时候默认值和选项也会发挥作用。

对象类型

当我们请求是一个对象的时候

不对模型设置文档注解

此时我们请求一个没有添加文档注解的对象。

    /**
     * 测试对入参对象不添加注解
     * @param user
     * @return
     */
    @ApiOperation(value="参数为对象请求,此时不对参数加额外注释(请求描述)",
            notes="参数为对象请求的注释(注释)",
            httpMethod = "POST")
    @RequestMapping(value = "bean",method = RequestMethod.POST)
    public String testBeanParams(User user) {
        log.info("传入参数:",JSON.toJSONString(user));
        return "传入参数:"+JSON.toJSONString(user); 
    }

这个时候swagger可以将对象参数进行解析，但是因为没有添加注解，所以显示的知识属性名称。

对模型设置文档注解

@Data
@ApiModel(value = "子类的请求对象",
        description = "请求对象描述",
        parent = QueryBaseRequest.class)
public class QueryUserRequest extends QueryBaseRequest {
    
    @ApiModelProperty(name = "name",
            value = "name值",
            dataType = "String",
            example = "默认显示的值",
            allowEmptyValue = true)
    private String name;

    @ApiModelProperty(name = "param1",
            value = "这个参数会被隐藏",
            dataType = "String",
            required = true,
            hidden = true)
    private String param1;


    @ApiModelProperty(name = "param2",
            value = "参数2，这个参数必填",
            dataType = "String",
            required = true,
            allowableValues = "值1,值2,值3")
    private String param2;
}

此时对参数的对象设置文档注解，再去查看API文档页面

此时就可以显示文档中设置的内容了。

请求返回内容的注解

swagger除了支持对请求controller和请求方法，以及入参进行注解，还支持对返回内容提供注解。

配置返回对象

通常我们不仅要向他人提供传递参数的文档还需要提供返回内容，正确以及错误结果的内容，这个时候可以使用ApiResponses注解

• 正常内容的注解

@Data
@ApiModel(value = "用户的包装类",description = "用户的包装类描述")
public class UserWrapper {

    @ApiModelProperty(name = "id",
            value = "id的值",
            dataType = "java.lang.Long")
    private Long id;

    @ApiModelProperty(name = "name",
            value = "name值",
            dataType = "String")
    private String name;
    @ApiModelProperty(name = "age",
            value = "age值",
            dataType = "java.lang.Integer")
    private Integer age;
    @ApiModelProperty(name = "money",
            value = "money值",
            dataType = "java.lang.Double")
    private Double money;

    public UserWrapper(User user) {
        this.id = user.getId();
        this.name = user.getName();
        this.age = user.getAge();
        this.money = user.getMoney();
    }
}

-错误内容的注解

@Data
@ApiModel(value = "错误的返回值",description = "错误的返回值")
public class ErrorRest {
    /**
     * 返回code
     */
    @ApiModelProperty(name = "code",
            value = "错误的code",
            dataType = "java.lang.Integer",
            example = "500")
    private Integer code;

    /**
     * 返回错误信息
     */
    @ApiModelProperty(name = "name",
            value = "错误信息",
            dataType = "String",
            example = "错误数据")
    private String message;

    /**
     * 返回错误的结果集
     */
    @ApiModelProperty(name = "data",
            value = "错误数据",
            dataType = "Object",
            example = "{}")
    private String data;
}

请求内容

    @ApiOperation(value="对象请求返回对象(请求描述)",
            notes="对象请求返回对象的注释(注释)",
            httpMethod = "POST",
            responseHeaders = {
                    @ResponseHeader(name="dai",description = "头信息的补充")
            },
            code = 201)
    @ApiResponses({
            @ApiResponse(code = 200,message = "成功",response = UserWrapper.class),
            @ApiResponse(code = 500,message = "服务器错误",response = ErrorRest.class)
    })
    @RequestMapping(value = "beanToBean",method = RequestMethod.POST)
    public UserWrapper testBeanParamsReturnBean(User user) {
        log.info("传入参数:",JSON.toJSONString(user));
        return new UserWrapper(user);
    }

此时查看API文档，我们将展示内容切换至Model就可以看到配置的内容了。

其他配置

Path类型的参数

    @ApiOperation(value="GET请求注释(请求描述)",
            notes="GET请求注释(注释)",
            httpMethod = "GET")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "id的描述",
                    defaultValue = "2333",
                    dataTypeClass = Integer.class,paramType = "path",
                    example = "2333")
    })
    @RequestMapping(value = "{id}",method = RequestMethod.GET)
    public String testPath(@PathVariable("id") Integer id) {
        log.info("传入参数:",JSON.toJSONString(id));
        return "传入参数:" + id;
    }

参数的效果

隐藏某些接口

1、可以配置参数idden = true来隐藏这个接口

@Api(value = "控制器隐藏",
        tags = "控制器隐藏(此注解将被隐藏)",
        hidden = true)
@RestController
@RequestMapping("classHidden")
public class TestClassAnnotationsHiddenController {
    
}

2、 或者使用@ApiIgnore来忽略接口生成

@ApiIgnore(value = "注解标注忽略")
@Api("User相关请求控制器")
@RestController
@RequestMapping("user")

模型的文档

在文档下部的Models中可以看到接口返回对象中的数据模型。

页面的替换

对于很多人来说，原生的页面并不是那么习惯。所以现在有很多可以替换swagger默认界面的方法。这一块因为之前并没有准备这块代码，也没有测试网上的那些方法。所以这里就先不说了，有兴趣的可以多搜一搜，有非常多的结果的。

---

本篇文章涉及的源码下载地址：https://gitee.com/daifyutils/springboot-samples

附录：swagger常用注解

基于对象的注解

注解	注解属性	描述
@ApiModel		用对象来接收参数
	value	对象名称
	description	描述
	parent	父类
	discriminator	判断使用哪个子类型的逻辑
	subTypes	子类型数组
	reference	类型引用
@ApiModelProperty		用对象接收参数时，描述对象的一个字段
	value	此属性的简要描述
	name	属性名称
	allowableValues	限制此参数的可接受值
	access	允许从API文档中筛选属性。请参见io.swagger.core.filter.swaggerspecfilter
	dataType	参数的数据类型
	required	指定是否需要参数
	position	允许显式排序模型中的属性
	hidden	配置为true ，将在文档中隐藏
	example	参数的单个示例
	accessMode	允许指定模型属性的访问模式
	reference	类型引用
	allowEmptyValue	允许传递空值
	extensions	an optional array of extensions

基于控制器注解配置

注解	注解属性	描述
@Api		修饰整个类，描述Controller的作用
	value	在没有设置tags前描述此类的作用
	tags	如果设置这个值、value的值会被覆盖，同样是对此注解的描述
	produces	对应于此资源下操作的“products”字段。如, “application/json, application/xml”
	consumes	对应于此资源下操作的“consumes”字段。如, “application/json, application/xml”
	protocols	协议类型，如: http, https, ws, wss.
	authorizations	对应于操作对象的“security”字段，开启安全认证时使用
	hidden	配置为true ，将在文档中隐藏

基于请求注解配置

注解	注解属性	描述
@ApiOperation		描述一个类的一个方法，或者说一个接口
	value	接口说明
	notes	接口发布说明
	tags	如果设置这个值、value的值会被覆盖，同样是对此注解的描述
	response	接口返回参数类型
	responseContainer	设置废弃？
	responseReference	指定对响应类型的引用。指定的引用可以是本地引用，也可以是远程引用
	httpMethod	接口请求方式
	nickname	对应于“operationid”字段。
	produces	对应于此资源下操作的“products”字段。如, “application/json, application/xml”
	consumes	对应于此资源下操作的“consumes”字段。如, “application/json, application/xml”
	protocols	协议类型，如: http, https, ws, wss.
	authorizations	对应于操作对象的“security”字段，开启安全认证时使用
	hidden	配置为true ，将在文档中隐藏
	responseHeaders	请求头信息的描述
	code	http的状态码 默认 200
	extensions	扩展属性
	ignoreJsonView	解析操作和类型时忽略JSONVIEW注释。为了兼容
@ApiParam		单个参数描述
	name	参数名称
	value	参数的简要描述
	defaultValue	默认参数值
	allowableValues	参数名
	required	参数是否需要传递
	access	允许从API文档中筛选参数
	allowMultiple	指定参数是否可以通过多次出现来接受多个值。
	hidden	配置为true ，将在文档中隐藏
	example	参数的单个示例
	examples	参数示例。仅适用于BodyParameters
	type	添加重写检测到的类型的功能
	format	添加提供自定义格式的功能
	allowEmptyValue	添加将格式设置为空的功能
	readOnly	添加被指定为只读的功能
	collectionFormat	添加用“array”类型重写collectionformat的功能
@ApiResponse		HTTP响应其中1个描述
	code	响应的HTTP状态代码
	message	响应附带的可读消息
	response	用于描述消息有效负载的可选响应类。
	reference	类型引用
	responseHeaders	响应旁边提供的可能头的列表
	responseContainer	宣布容器的反应有误
	examples	参数示例。
@ApiResponses		HTTP响应整体描述
	value	ApiResponse的列表。
@ApiIgnore		使用该注解忽略这个API
	value	API被忽略的描述。
@ApiImplicitParam		一个请求参数
	name	参数名称。
	value	参数描述。
	defaultValue	参数默认值。
	value	API被忽略的描述。
	allowableValues	限制此参数的可接受值
	required	指定是否需要参数
	access	允许从API文档中筛选属性。请参见io.swagger.core.filter.swaggerspecfilter
	allowMultiple	指定参数是否可以通过多次出现来接受多个值。
	dataType	参数的数据类型
	dataTypeClass	参数对应的字节码对象
	paramType	参数类型，path、query、body、header、form
	example	参数的单个示例
	examples	参数示例。
	type	添加重写检测到的类型的功能
	format	自定义格式的功能
	allowEmptyValue	允许传递空值
	readOnly	添加被指定为只读的功能
	collectionFormat	添加用“array”类型重写collectionformat的功能
@ApiImplicitParams		多个请求参数
	value	ApiImplicitParam的集合。