Springboot2（39）集成swagger2

源码地址

springboot2教程系列

添加依赖

<!-- swagger生成接口API -->
<dependency>
	<groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<!-- 接口API生成html文档 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>
        
<!-- 上面两个jar的必须的，下面这个是第三方的UI界面的美化，不是必需的 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.6</version>
</dependency>

添加配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                 //扫描包路径
                .apis(RequestHandlerSelectors.basePackage("cn.myframe.controller"))
                .paths(PathSelectors.any()).build();

    }

    //构建api文档的详细信息函数
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                //页面标题
                .title("springBoot测试使用Swagger2构建RESTful API")
                //创建人
                .contact(new Contact("yuniuzai","","ynz@myframe.cn"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }


}

Controller类

@Api(tags="zookeeper基本操作")
@RequestMapping("/zk")
@RestController
@Slf4j
public class ZookeeperController {

    @Autowired
    private ZkClient zkClient;

    @Autowired
    private ZkClient zkClientTest;

    /**
     * 创建节点
     * @param type
     * @param znode
     * @return
     */
    @ApiOperation(value = "创建节点",notes = "在命名空间下创建节点")
    @ApiImplicitParams({
            @ApiImplicitParam(name ="type",value = "节点类型:<br> 0 持久化节点<br> 1 临时节点<br>  2 持久顺序节点<br> 3 临时顺序节点",
                    allowableValues = "0,1,2,3",defaultValue="3",paramType = "path",required = true,dataType = "Long"),
            @ApiImplicitParam(name ="znode",value = "节点名称",paramType = "path",required = true,dataType = "String"),
            @ApiImplicitParam(name ="nodeData",value = "节点数据",paramType = "body",dataType = "String")
    })
    @RequestMapping(value = "/create/{type}/{znode}",method=RequestMethod.POST)
    private String create(@PathVariable Integer type,@PathVariable String znode,
                          @RequestBody String nodeData){
        ...
    }
}
        

常用注解说明

@Api：用在请求的类上

1. 表示对类的说明 tags=“说明该类的作用，可以在UI界面上看到的注解” value="该参数没什么意义，在UI 界面上也看到，所以不需要配置"

@ApiOperation：用在方法上，说明方法的作用

1. ​ value: 表示接口名称
2. ​ notes: 表示接口详细描述

@ApiImplicitParams：用在方法上包含一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

1. name：参数名
2. dataType：参数类型
3. required：参数是否必须传
4. value：参数的描述
5. defaultValue：参数的默认值
6. allowableValues:允许选择的值范围
7. paramType：参数位置
   • header 对应注解：@RequestHeader
   • query 对应注解：@RequestParam
   • path 对应注解: @PathVariable
   • body 对应注解: @RequestBody

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

1. code：状态码
2. message：返回自定义信息
3. response：抛出异常的类

@ApiIgnore: 表示该接口函数不对swagger2开放展示

访问地址

http://localhost:端口号/项目名称/swagger-ui.html

第三方的UI界面地址/doc.html，基于本项目地址是http://localhost:端口号/项目名称/doc.html