添加依赖
<!-- 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:用在请求的类上
- 表示对类的说明 tags=“说明该类的作用,可以在UI界面上看到的注解” value="该参数没什么意义,在UI 界面上也看到,所以不需要配置"
@ApiOperation:用在方法上,说明方法的作用
- value: 表示接口名称
- notes: 表示接口详细描述
@ApiImplicitParams:用在方法上包含一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
- name:参数名
- dataType:参数类型
- required:参数是否必须传
- value:参数的描述
- defaultValue:参数的默认值
- allowableValues:允许选择的值范围
- paramType:参数位置
- header 对应注解:@RequestHeader
- query 对应注解:@RequestParam
- path 对应注解: @PathVariable
- body 对应注解: @RequestBody
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
- code:状态码
- message:返回自定义信息
- response:抛出异常的类
@ApiIgnore: 表示该接口函数不对swagger2开放展示
访问地址
http://localhost:端口号/项目名称/swagger-ui.html
第三方的UI界面地址/doc.html
,基于本项目地址是http://localhost:端口号/项目名称/doc.html