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
出现如下效果