SpringBoot RestFul集成Swagger2

一、依赖：

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

二、新增配置项：

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bosssoft.platform.appframe.rest"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("应用中心springBoot之RestFulApi接口文档")
                .version("1.0")
                .build();
    }
}

通过@Configuration注解，表明它是一个配置类，@EnableSwagger2开启swagger2。apiINfo()配置一些基本的信息。apis()指定扫描的包会生成文档。

三、写生产文档的注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiParamImplicitL：一个请求参数
@ApiParamsImplicit 多个请求参数
例如：

/**
 * 
 * @author Shaw
 *
 */
@RestController
@RequestMapping(value = "/rest", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@Api(value = "/rest", tags = "ApplicationRestController", description = "应用管理接口")
public class ApplicationRestController{
    
    @Autowired
    private AfaApplicationService applicationService;
    
    @ApiOperation("获取所有应用")
    @RequestMapping(value="/application",method=RequestMethod.GET)
    public List<ApiApplication> getApplications() {
        AfaApplication app = new AfaApplication();
        app.setIsOpen("1");
        List<AfaApplication> afaAppList = applicationService.getAfaApplicationList(app);
        return BeanUtils.copyList(afaAppList, ApiApplication.class);
    }
    
    @ApiOperation("根据用户编码获取当前用户应用")
    @RequestMapping(value="/application/userCode/{userCode}",method=RequestMethod.GET)
    public List<ApiApplication> getApplicationsByUserCode(@PathVariable("userCode")String userCode) {
        return BeanUtils.copyList(applicationService.getApplicationsByUserCode(userCode),ApiApplication.class);
    }

}

启动项目，访问：

http://127.0.0.1:8088/appframe-web/swagger-ui.html

 

 测试的时候，可以直接在这个ui界面上进行测试，或者可以通过postman或者soapui等工具进行测试。

备注可以通过修改依赖，将Ui的测试界面改成bootstrap风格的Api界面 

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

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.4</version>
        </dependency>

 风格如下：

http://127.0.0.1:8088/appframe-web/doc.html