springboot项目集成Swagger2

不仅仅是springboot，其他spring项目均可集成swagger，在项目开发中，众多的接口都要有接口文档，并且很容易出现纰漏和代码与文档不一致的情况，利用swagger来自动生成api文档，让代码维护与文档维护保持一致，大大减少文档编写和维护的工作量，并且swagger2还提供了强大的页面测试功能来调试每个RESTful API。

1.加入jar包依赖

<!-- swagger -->
<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>

2.创建swagger2配置类

通过 @Configuration 注解，让Spring来加载该类配置。再通过 @EnableSwagger2 注解来启用Swagger2。本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被 @ApiIgnore 指定的请求）。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.nio.exam"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("这是一个description")
.termsOfServiceUrl("http://blog.csdn.net/innerpeacescorpio")
.contact("jingling")
.version("1.0")
.build();
}
}

3.编写接口配置自定义的文档内容

@RestController
@RequestMapping(value="/test")
public class SwaggerTestController {

@ApiOperation(value="测试接口", notes="测试接口详细描述")
@RequestMapping(value="/id", method=RequestMethod.PUT)
public String doSomething(@ApiParam(required=true, name="channelId", value="渠道ID") @RequestParam Integer channelId,
@ApiParam(required=true, name="operator", value="操作人") @RequestParam String operator,
@ApiParam(required=true, name="map", value="参数") @RequestParam Map<String, Object> map){
return "hello";
}

}

4.访问

启动springboot程序，访问http://localhost:8002/swagger-ui.html

出现如下效果