spring-boot接入swagger2接口文档

文章概述

本篇文章介绍spring-boot接入swagger2接口文档。

配置步骤

添加maven依赖（2.8.0风格略丑，这里用2.7.0版本）:

<dependencies>
<!--swagger2 -->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.7.0</version>
	</dependency>
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.7.0</version>
	</dependency>
</dependencies>

添加swagger配置类:

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
//                .apis(RequestHandlerSelectors.basePackage("com.ls.sbe")) // 扫描该包下所有controller文件
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) // 仅扫描ApiOperation注解的方法
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("for spring boot project")
                .version("1.0.0")
                .build();
    }
}

配置相关Controller以及接口方法注解；
启动服务，访问：http://localhost:8083/swagger-ui.html

Swagger接口注解

Controller接口类注解

@Api

概述

ApiController接口类说明注解：@Api,作用在XController上。

使用示例

@Api(tags = "case-api", description = "HTTP请求方法示例")
@RestController
@RequestMapping(value = "/httpApi")
public class HttpApiRestController {}

参数配置：

value：controller接口路径或类别名（无效）；
tags：controller接口类别名，如果设置这个值、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 将在文档中隐藏；

接口方法注解

@ApiOperation

概述

对API接口XController类中，具体接口方法的协议配置注解：@ApiOperation，用在controller的方法上；

使用示例

1	@ApiOperation(value = "GET请求", notes = "GET请求-参数query",produces = "application/json;charset=UTF-8")

参数配置：

value：url的路径值；
tags：如果设置这个值、value的值会被覆盖；
notes：方法的具体描述；
description：对api资源的描述；
basePath：基本路径可以不配置；
position：如果配置多个Api 想改变显示的顺序位置；
produces：Content-Type响应数据类型，For example, “application/json, application/xml”；
consumes：For example, “application/json, application/xml”；
protocols：Possible values: http, https, ws, wss；
authorizations：高级特性认证时配置；
hidden：配置为true 将在文档中隐藏；
response：返回的对象（如：response = CommonDto.class）；
responseContainer：这些对象是有效的 “List”, “Set” or “Map”.，其他无效；
httpMethod：”GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”；
code：http的状态码默认 200；
extensions：扩展属性；

方法参数注解

@ApiImplicitParams：参数集；
@ApiImplicitParam：单个参数；

概述

用在controller的方法上，单个参数用@ApiImplicitParam，多个参数用@ApiImplicitParams（内部单个参数用@ApiImplicitParam）。

使用示例

@ApiImplicitParam(name = "tag", value = "标签", required = true, dataType = "String", paramType = "query")

@ApiImplicitParams({
        @ApiImplicitParam(name = "tag", value = "标签", required = true, dataType = "String", paramType = "query"),
        @ApiImplicitParam(name = "tag2", value = "标签2", required = true, dataType = "String", paramType = "query")
})

参数配置：

name：接收参数名；
value：接收参数的意义描述；
required：参数是否必填（true/false）；
defaultValue: 默认值；
dataType：参数的数据类型，只作为标志说明，并没有实际验证；
hidden：隐藏该属性；
example：举例子；

1	Long/String等等；

paramType：查询参数类型；

- path	以地址的形式提交数据；
- query	直接跟参数完成自动映射赋值；
- body	以流的形式提交 仅支持POST；
- header	参数在request headers 里边提交；
- form	以form表单的形式提交 仅支持POST；

数据实体类注解

概述

@ApiModel 表明这是一个被swagger框架管理的model，用于class上；
@ApiModelProperty 这里顾名思义，就是标注在被标注了@ApiModel的class的属性上；

使用示例

@ApiModel(description = "返回|请求 对象")
public class CommonDto {
    @ApiModelProperty(value = "标题")
    private String title;
    @ApiModelProperty(value = "消息")
    private String message;
}

响应码说明注解

@ApiResponses

概述

作用在controller内接口方法上，说明一些状态码的含义；

使用示例

@ApiResponses({
    @ApiResponse(code = 300, message = "http 300"),
    @ApiResponse(code = 4300, message = "http 4300")
})