使用springfox整合Springboot和Swagger

Swagger 是一系列对 RESTful 接口进行规范描述和页面展示的工具. 通过 springfox-swagger 将 Swagger 与 Spring-MVC 整合, 可从代码中的注解获取信息, 并生成相应的文档. 效果如下所示.

下面开始集成：

首先导入依赖：

<!--REST API UI-->
		<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>		

然后开启swagger配置：

package com.bigdata.lab.ymlib.config;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * REST API UI
 * @author 
 * @update 2017年10月27日 下午12:02:07
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
  @Bean
  public Docket createRestApi() {
      return new Docket(DocumentationType.SWAGGER_2)
              .apiInfo(apiInfo())
              .select()
              .apis(RequestHandlerSelectors.basePackage("com.bigdata.lab.ymlib.rest"))
              .paths(PathSelectors.any())
              .build();
  }

  private ApiInfo apiInfo() {
      return new ApiInfoBuilder()
              .title("xxxx")
              .description("xxxx")
              .termsOfServiceUrl("xxxx")
              .contact("xxxx")
              .version("1.0")
              .build();
  }


}

然后写一个简单服务：

@ApiOperation(value = "获取某个活动")
	@RequestMapping(value = "/{saleActivityId}", method = RequestMethod.GET)
	public ResponseEntity<ReturnMsg<SaleActivity>> getSaleActivities(@PathVariable("saleActivityId") String saleActivityId) throws YMLibWebApplicationException{
		Assert.notNull(saleActivityId);
		ReturnMsg<SaleActivity> msg = new ReturnMsg<SaleActivity>();
		List<SaleActivity> data=new ArrayList<SaleActivity>();
		try {
			SaleActivity  saleActivity=saleActivityRepository.findOne(saleActivityId);
			data.add(saleActivity);
		} catch (Exception e) {
			throw new YMLibWebApplicationException("查询出错！");
		}
		msg.setData(data);
		msg.setCode(200);
		msg.setMsg("查询成功");
		return ResponseEntity.ok(msg);
	}

网上的例子：

@Api(value = "User控制器")
@Controller
@RequestMapping("/user")
public class UserController {
    @ApiOperation(value = "根据用户id查询用户信息", httpMethod = "GET", produces = "application/json")
    @ApiResponse(code = 200, message = "success", response = Result.class)
    @ResponseBody
    @RequestMapping(value = "queryUserById", method = RequestMethod.GET, produces = "application/json")
    public Result queryUserById(@ApiParam(name = "userId", required = true, value = "用户Id") @RequestParam("userId") int userId, HttpServletRequest request) {
        User user = new User(userId, "haoyifen", 24);
        Result result = new Result();
        result.setCode(0);
        result.setData(user);
        result.setMessage("success");
        return result;
    }
}

常用的几个用于生成文档的注解如下: 
- @Api 表示该类是一个 Swagger 的 Resource, 是对 Controller 进行注解的 
- @ApiOperation 表示对应一个 RESTful 接口, 对方法进行注解 
- @ApiResponse 表示对不同 HTTP 状态码的意义进行描述 
- @ApiParam 表示对传入参数进行注解

访问地址：

http://localhost:9080/ymlib/swagger-ui.html#/

效果如下图