SpringMVC集成Swagger

1. 简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新 。接口的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

2. 添加Swagger2依赖

注意：
只添加下面两个依赖的前提是SpringMVC的项目能够正常运行

<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.6.1</version>
</dependency>

<!--swagger-ui是提供API接口页面展示的-->
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.6.1</version>
</dependency>

3. 创建Swagger2配置类

3.1 自定义配置类

//启用Swagger2
@EnableSwagger2        
public class Swagger2Config extends WebMvcConfigurationSupport {
   
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).select()
                //扫描指定包中的swagger注解
                //.apis(RequestHandlerSelectors.basePackage("com.xia.controller"))
                //扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }


    @Bean
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("基础平台 RESTful APIs")
                .description("基础平台 RESTful 风格的接口文档，内容详细，极大的减少了前后端的沟通成本，同时确保代码与文档保持高度一致，极大的减少维护文档的时间。")
                .termsOfServiceUrl("http://xiachengwei5.coding.me")
                .version("1.0.0")
                .termsOfServiceUrl("http://xxx.xxx.com")
                .license("LICENSE")
                .licenseUrl("http://xxx.xxx.com")
                .build();
    }
    
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
    
}

3.2 使用xml中配置

<bean class="springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration" id="swagger2Config"/>
<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>

4. 初步展示效果

5. 编写常用Swagger注解

添加Swagger注解，能够让Swagger的APi文档页面更加友好，更加方便理解和调试

5.1 实体注解

@ApiModel() 用于类,表示对类进行说明，用于参数用实体类接收
- value–表示对象名
- description–描述
@ApiModelProperty() 用于方法，字段；表示对model属性的说明或者数据操作更改
- value:字段说明
- name:重写属性名字
- dataType:重写属性类型
- required:是否必填
- example:举例说明
- hidden:隐藏

用法如下代码所示：

@ApiModel(value = "UserInfo:用户信息")
public class UserInfo implements Serializable {
    @ApiModelProperty(value = "ID")
    private Integer id;

    @ApiModelProperty(value = "登录账号", required = true)
    private String userNo;

    @ApiModelProperty(value = "姓名", required = true)
    private String userName;
}

显示效果如下所示：

5.2 控制类注解

下面的这些注解都放在Controller控制器类上面

5.2.1 @Api

修饰整个类，描述Controller的作用

@Api(tags = {"用户操作接口"})
@RestController
@RequestMapping(value = "/userInfo")
public class UserInfoController {

}

tags：控制类功能说明，tags是一个字符串数组，可以添加多个标签

tags = {"用户操作接口","对用户的一些增删改查操作"}

效果如下：

value:也是说明，可以使用tags替代

5.2.2 @ApiOperation

描述一个类的一个方法，或者说一个接口

    @GetMapping(value = "/selectOne")
    @ApiOperation(value = "value作用：查询单个人员信息", notes = "notes作用：输入用户ID",tags = {"查询"})
    public ZingResult selectOne() {
        return ZingResult.success();
    }

    @GetMapping(value = "/update")
    @ApiOperation(value = "value作用：更新用户信息", notes = "notes作用：输入用户各项参数",tags = {"更新"})
    public ZingResult update() {
        return ZingResult.success();
    }

value用于方法描述
notes用于提示内容

tags可以重新分组

5.2.3 @ApiParam

单个参数描述

name–参数名
value–参数说明
required–是否必填

@GetMapping(value = "/selectOne")
    @ApiOperation(value = "value作用：查询所有的人员信息并分页展示", notes = "notes作用：输入page和size来分页查询", tags = {"查询"})
    public ZingResult selectOne(@ApiParam(name="page",value="页码",required=true) Integer page,@ApiParam(name="size",value="数量",required=true) Integer size) {
        return ZingResult.success();
    }

5.2.4 @ApiImplicitParams()和@ApiImplicitParam

用于方法，包含多个@AplimplicitParam

name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明

@ApiImplicitParams({
        @ApiImplicitParam(name = "page", value = "跳转到的页数", required = true, paramType = "query"),
        @ApiImplicitParam(name = "size", value = "每页展示的记录数", required = true, paramType = "query")
})
public ZingResult selectAllUsers(Integer page, Integer size) {
    return ZingResult.success();
}

效果如下图所示：

5.2.5 @ApiIgnore()

用于类或者方法上，可以不被swagger显示在页面上
比较简单, 这里不做举例

6. 加载配置文件

加载配置文件中的内容，灵活配置swagger APIinfo的信息

注意Spring的@Value读取配置文件中的中文会乱码

6.1 配置文件

#Swagger开关
SWAGGER.ENABLE = true

#Swagger API配置
SWAGGER.TITLE = 基础平台 RESTful APIs
SWAGGER.DESC = 基础平台 RESTful 风格的接口文档，内容详细，极大的减少了前后端的沟通成本，同时确保代码与文档保持高度一致，极大的减少维护文档的时间。

6.2 加载配置文件，并制定utf-8编码

使用PropertyPlaceholderConfigurer加载

<!-- 加载配置文件 -->
<bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
    <property name="locations">
        <list>
            <value>classpath:dubbo-server.properties</value>
            <value>classpath:server.properties</value>
        </list>
    </property>
    <property name="fileEncoding" value="utf-8" />
</bean>

使用context:property-placeholder 加载

<context:property-placeholder location="classpath:conf/*.properties" file-encoding="UTF-8"/>

使用注解加载

@PropertySource(value = "classpath:conf/copyWriteUI.properties",encoding = "utf-8")