springfox-swagger2 || rap

矫情吗；* 2022-05-15 11:39 184阅读 0赞

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

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.7.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.7.0</version>
    </dependency>

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", "chang_hfeng@163.com"))
                    .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`即可

[rap_swagger]: https://blog.csdn.net/i6448038/article/details/77622977