Swagger：JAVA 前后端调试利器，接口文档自动生成工具的简单使用示例

1.关于Swagger

Swagger可以根据JAVA的接口代码，自动生成html浏览页面，极大的方便了前端开发人员调用后端接口，还能根据代码的更新而自动更新，而且使用非常简单代码少，减少了手动编写整理接口文档的时间精力和后期维护工作量。

以下介绍Springboot 集成swagger2 即springfox-swagger2的方法。

生成的接口文档预览界面

Controller源代码界面

下面介绍如何配置和使用。

2.引入pom依赖包

        <!--SpringBoot整合Swagger-ui-->
        <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>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

将配置类SwaggerConfig.java文件放在config文件夹下，SwaggerConfig.java内容如下(包名需要修改成自己的)。

package com.mydemo.config;


import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
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;

/**
 * @ClassName SwaggerConfig
 * @Description TODO
 */
// 启动时加载类
@Configuration
// 启用Swagger API文档
@EnableSwagger2
//动态添加响应类注释字段
@EnableSwaggerBootstrapUI
//@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("SwaggerConfig组")
                .select()
                // 自行修改为自己的包路径
                .apis(RequestHandlerSelectors.basePackage("com.mydemo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("my管理系统")
                .description("my管理系统 API 1.0 操作文档")
                //服务条款网址
                .termsOfServiceUrl(" ")
                .version("1.0")
                .contact(new Contact("quan", " ", "***@*.com"))
                .build();
    }

}

3.在启动类加上注解@EnableSwagger2

在项目启动类SpringBootWebApplication中开启@EnableSwagger2注解，使得用在controller中的swagger注解生效，覆盖的范围下的所有controller。

4.Controller 类配置

在Controller类的方法头进行注解设置。

说明一点，入参如果是实体类，则Swagger会自动扫描到类的成员变量，并在文档列表中展现，实体类中的字段属性也会自动带出。

但有的后端开发人员使用的入参是hashmap这样的非实体类，就需要用代码手动做动态添加响应类注释，以便于Swagger接口文档可以根据设置来显示hashmap里面的入参。

实体类入参这里就不介绍了(设置方法见下文的第5点)。以下介绍入参是hashmap类的情况。

    /**
     * 查询多条记录
     * @param map arch_id,order_by
    */
    @ApiOperation(value = "查询多条记录",notes="查询多条记录列表")
     @DynamicParameters(name = "map",properties = {
            @DynamicParameter(value = "档案id",name = "arch_id",example = "254"),
            @DynamicParameter(value = "小区id",name = "area_id",example = "1"),
            @DynamicParameter(value = "排序",name = "order_by",example = "arch_id")
    })
    @RequestMapping(value = "/getList", method = RequestMethod.POST)
    @ResponseBody
    public String getList(HttpServletResponse response, @RequestBody HashMap<String, Object> map) {
        String estr = "获取列表(getList)===：";
        ResultMsg rMsg = new ResultMsg();
        try {

            //...TODO ...
            
        } catch (Exception e) {
            logger.error(estr + e.toString());
            return rMsg;
        }
        return "";
    }

ApiOperation：文档中接口的名称和说明

DynamicParameters：动态添加响应类注释字段(参见https://doc.xiaominfo.com/guide/dynamicResponse.html)

DynamicParameter：入参属性，name：参数名，value：参数注释说明 example：参数示例值。

入参的类型要设置为@RequestBody，将即前端传递的参数自动转换json字符串类型接收。

5.返回实体类参数

如果返回参数是实体类，只要在该实体类名头设置注解@ApiModel，成员属性设置注解@ApiModelProperty，

接口文档就可以自动显示该实体类的参数类型。同理，入参实体类也是这样注解设置。

ResultMsg.java实体类的定义如下：

@ApiModel(description= "返回响应数据")
public class ResultMsg implements Serializable {

    @ApiModelProperty(value = "业务错误代码")
    private String resultCode;// 业务错误，前端依据此返回码给出客户提示

    @ApiModelProperty(value = "返回执行消息内容")
    private String resultMsg;

    @ApiModelProperty(value = "返回list队列")
    private List list;

    @ApiModelProperty(value = "返回对象")
    private Object entity;

    @ApiModelProperty(value = "是否成功")
    private boolean success;// 执行结果

//getter...seter
}

文档的显示效果如下：

以上设置完毕。

查看接口文档方法：

启动项目，在项目地址http://127.0.0.1:端口/项目名/doc.html下就可以看到接口文档。

6.在线调试

生成的接口可以在线测试，点击左边的调试，因为我们在接口代码已经预设了参数示例值，所以输入框字段值会自动预设。直接点击发送按钮，前端就会请求后端controller接口，并返回正确的数据。