SpringBoot之Swagger2

​ Swagger 2是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。下面介绍如何使用Swagger 2。

配置Swagger 2的依赖

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

创建Swagger2配置类

在 Application.java 同级创建 Swagger2.java

@Configuration
@EnableSwagger2
public class Swagger2 {
	@Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.comunication.messagesent.mechanism.api.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .contact("luckylau")
                .version("1.0")
                .build();
    }

}

​ 通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容。

API控制层配置

@RestController
@RequestMapping(path = "/messageSent", produces = { "application/json;charset=UTF-8" })
@Api(value = "API统一管理入口")
public class MessageSendController {
	private static final Logger logger = LoggerFactory.getLogger(MessageSendController.class);
	@Autowired
	private SenderService senderService;
	@ApiOperation(value = "创建用户", notes = "根据SenderInfo对象创建用户")
	@ApiImplicitParam(name = "senderInfo", value = "用户详细实体", required = true, dataType = "SenderInfo")
	@RequestMapping(value = "/sender", method = RequestMethod.POST)
	public SenderInfo addSender(@RequestBody SenderInfo senderInfo) throws ApiException {
		logger.info("添加用户成员" + senderInfo.toString());
		try {
			return senderService.addSender(senderInfo);
		} catch (Exception e) {
			// TODO Auto-generated catch block
			throw new ApiException(e.getMessage());
		}

	}
	@ApiOperation(value = "列出所有的用户成员")
	@RequestMapping(value = "/senders", method = RequestMethod.GET)
	public List<SenderInfo> listSenders() {
		logger.info("列出所有的用户成员");
		return senderService.findAllSenderInfo();
	}
	@ApiOperation(value = "根据别名获取用户信息")
	@ApiImplicitParam(name = "alias", value = "用户别名", required = true, paramType = "path", dataType = "String")
	@RequestMapping(value = "/sender/{alias}", method = RequestMethod.GET)
	public SenderInfo getSender(@PathVariable("alias") String alias) {
		logger.info("获取别名为	" + alias + " 用户");
		SenderInfo si = senderService.findByAlias(alias);
		return si;
	}

	@ApiOperation(value = "根据别名删除用户信息")
	@ApiImplicitParam(name = "alias", value = "用户别名", required = true, paramType = "path", dataType = "String")
	@RequestMapping(value = "/sender/{alias}", method = RequestMethod.DELETE)
	public void deleteSender(@PathVariable("alias") String alias) {
		logger.info("删除别名为	" + alias + " 用户");
		senderService.deleteSender(alias);
	}

	@ApiOperation(value = "删除所有的用户成员")
	@RequestMapping(value = "/senders", method = RequestMethod.DELETE)
	public void deleteAllSender() {
		logger.info("删除所有的用户");
		senderService.deleteAllSender();
	}

	@ApiOperation(value = "更新用户是否激活的状态", notes = "根据url的别名来指定更新对象")
	@RequestMapping(value = "/sender/{alias}", method = RequestMethod.PUT)
	@ApiImplicitParams({
			@ApiImplicitParam(name = "alias", value = "用户别名", required = true, paramType = "path", dataType = "String"),
			@ApiImplicitParam(name = "isActive", value = "是否激活", required = true, paramType = "form", dataType = "Boolean") })
	public SenderInfo updateSender(@PathVariable("alias") String alias, @RequestParam("isActive") Boolean isActive) {
		logger.info("修改别名为	" + alias + " 用户的状态");
		return senderService.modifyActive(alias, isActive);
	}

}

@Api：用在类上，说明该类的作用，如：@Api(value = “API统一管理入口”)@ApiOperation：用在方法上，说明方法的作用@ApiImplicitParams：用在方法上包含一组参数说明@ApiImplicitParam：可以单独使用，也可以用在 @ApiImplicitParams 注解中；用户要了解其参数含义：name：参数名；value：参数的意思；required：参数是否必须传；paramType包括5种类型，分别是 header –> 请求参数的获取：@RequestHeader， query –>请求参数的获取：@RequestParam，path –> 请求参数的获取：@PathVariable，可以不显示标记，body –>如果paramType为空时候，会默认为body，form–>请求参数的获取：@RequestParam。dataType：参数类型。

项目为：MessagePushandEmailSend