Spring mvc Swagger2 API 集成记录

1、swargger 简介

Swagger™的目标是为REST APIs 定义一个标准的，与语言无关的接口，使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义，消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口，Swagger去掉了调用服务时的很多猜测。

现记录一下swargger 与spring mvc集成配置过程，以备忘。

2、jar包依赖

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

3、swagger配置文件

@Configuration
@EnableWebMvc
@EnableSwagger2
public class SwaggerConfig {
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2).enable(WebConfig.isEnableSwagger()).apiInfo(apiInfo()).select()
				.apis(RequestHandlerSelectors.basePackage("com.boco")).paths(PathSelectors.any()).build();
	}

	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("系统APIs").description("").termsOfServiceUrl("http://www.boco.com/")
				.version("1.0").build();
	}
}

其中 eable(boolean) 可以控制开启或关闭接口文档功能，在生产环境可将其关闭

4、Spring mvc中配置

在自动扫描目录中加入 springfox,

<context:component-scan
		base-package="springfox,......" />

静态资源列表中加入

<mvc:resources mapping="swagger-ui.html" location="classpath*:/META-INF/resources" />
<mvc:resources mapping="/webjars/**"
		location="classpath*:/META-INF/resources/webjars" />

5、Controller 方法中加入swargger注解

@RestController
@RequestMapping("/equipment")
public class EquipController extends BaseController {

	@Autowired
	private EquipmentService equipmentService;

	/**
	 * 获取设备类型列表及关联信息
	 */
	@ApiOperation("获取设备类型列表")
	@RequestMapping(value = "/getEquipTypes", method = RequestMethod.GET)
	public OutResult<List<EquipType>> getEquipTypeInfo(HttpServletRequest request, HttpServletResponse response) {
		OutResult<List<EquipType>> result = new OutResult<>();
		try {
			List<EquipType> equipTypes = equipmentService.getEquipTypes();
			returnSuccessInfo(result);
			result.setResult(equipTypes);
		} catch (Exception e) {
			log.error("获取设备类型列表异常", e);
			returnFailInfo(result);
		}

		return result;
	}

	/**
	 * 获取设备类型列表及关联信息
	 */
	@SuppressWarnings("unchecked")
	@ApiOperation("分页获取设备列表")
	@RequestMapping(value = "/getEquipments", method = RequestMethod.GET)
	public OutResult<PageBean<Equipment>> getEquipments(HttpServletRequest request,
			@ModelAttribute EquipmentQueryBo equipmentQueryBo) {
		OutResult<PageBean<Equipment>> result = new OutResult<>();
		try {
			Page<Equipment> equipments = equipmentService.selectByPage(equipmentQueryBo);
			returnSuccessInfo(result);
			result.setResult((PageBean<Equipment>) parsePageBean(equipments));
		} catch (Exception e) {
			log.error("获取设备列表异常", e);
			returnFailInfo(result);
		}

		return result;
	}

	/**
	 * 获取设备类型列表及关联信息
	 */
	@ApiOperation("保存设备")
	@RequestMapping(value = "/saveEquipment", method = RequestMethod.POST)
	public OutResult<?> saveEquipment(HttpServletRequest request, HttpServletResponse response,
			@ModelAttribute Equipment equipment) {
		OutResult<?> result = new OutResult<>();
		try {
			equipmentService.saveEquipment(equipment);
			returnSuccessInfo(result);
		} catch (ErrorInfoExeception e) {
			returnFailInfo(result);
			result.setMessage(e.getMessage());
		} catch (Exception e) {
			log.error("获取设备列表异常", e);
			returnFailInfo(result);
		}

		return result;
	}

	/**
	 * 删除设备
	 */
	@ApiOperation("删除设备")
	@RequestMapping(value = "/deleteByIds", method = RequestMethod.POST)
	public OutResult<?> deleteByIds(HttpServletRequest request, HttpServletResponse response,
			@ApiParam(value = "设备id字符串以逗号间隔", example = "1,2") @RequestParam String ids) {
		OutResult<?> result = new OutResult<>();
		try {
			equipmentService.deleteEquipmets(ids);
			returnSuccessInfo(result);
		} catch (ErrorInfoExeception e) {
			returnFailInfo(result);
			result.setMessage(e.getMessage());
		} catch (Exception e) {
			log.error("删除设备异常", e);
			returnFailInfo(result);
		}

		return result;
	}

}

对象中添加swargger注解

@ApiModel
public class Equipment {
	@Id
	@GeneratedValue(strategy = GenerationType.IDENTITY)
	@ApiParam("设备id")
	private Long id;

	@ApiParam("设备类型")
	private String type;

	@ApiParam(hidden = true)
	@Transient
	private String typeName;

	@ApiParam("设备编号")
	private String code;

	@ApiParam("设备名称")
	private String name;

	@ApiParam("ip")
	private String ip;

	@ApiParam("端口")
	private Integer port;

	@ApiParam(hidden = true)
	private Float longitude;

	@ApiParam(hidden = true)
	private Float latitude;

	@ApiParam("安装位置")
	private String address;

	// 省略getters setters

}

6、启动项目

通过连接访问api文档http://ip:port/{context path}/swagger-ui.html如下图所示