springfox-swagger2 || rap

一个介绍rap和swagger的网站
rap是阿里自研的一个api工具，以前用过需要手写保存，给前端的是一个压缩后的md文件列表，没接触swagger之前还以为是高级的。
近期接触swagger，发现集成到springboot还是很简单的，不需要配置，可直接使用提供的ui组件，不过很多注解会跟系统代码耦合在一起。以下是集成方法：
1、添加依赖

    io.springfox
    springfox-swagger2
    2.7.0


    io.springfox
    springfox-swagger-ui
    2.7.0

2、配置类
使用@EnableSwagger2开启swagger2

@Profile({"dev", "local", "test"})
@Configuration
@EnableSwagger2
public class Swagger2Config {

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("DEMO Restful APIs")
                .description("这个一个springboot集成swagger提供api文档的demo")
                // .termsOfServiceUrl("http://blog.csdn.net/chang_li")
                .contact(new Contact("changhf", "www.demo.com", "[email protected]"))
                .version("1.0")
                .build();
    }
}

3、注解记录

1. @ApiOperation在指定的路径上，对一个操作或HTTP方法进行描述。
   value对操作的简单说明，长度为120个字母，60个汉字。
   notes对操作的详细说明。

2. @ApiImplicitParams
   注解ApiImplicitParam的容器类，以数组方式存储。

3. @ApiImplicitParam
   对API的单一参数进行注解。
   name参数名称
   value参数的简短描述
   required是否为必传参数
   dataType参数类型，可以为类名，也可以为基本类型（String，int、boolean等）
   paramType参数的传入（请求）类型，可选的值有path, query, body, header or form。
   defaultValue参数默认值

    @ApiOperation(value = "分配任务", notes = "分配任务，即指定当前节点执行人")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "workItemId", value = "工作项id", required = true, dataType = "Long", paramType = "query"),
            @ApiImplicitParam(name = "userId", value = "用户id", required = true, dataType = "Long", paramType = "query", defaultValue = "110")
    })
    @GetMapping("/distributeTask")
    public WorkItemTaskDTO distributeTask(@RequestParam Long workItemId, @RequestParam Long userId) {
        try {
            return workflowService.distributeTask(workItemId, new UserDTO(userId, "lisi", 902L), null);
        } catch (Exception e) {
            log.error("分配任务失败", e);
        }
        return null;
    }

4、启动应用程序，访问localhost:8080/swagger-ui.html，点击Show/Hide即可