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 {@Beanpublic 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)@ResponseBodypublic 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接口，并返回正确的数据。