1、为什么使用swagger
Swagger是一种用于构建、文档化和调试RESTful API的开源框架。
2、如何引入?
可以使用bootstrapui来使得页面操作更加简洁。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
3、配置类
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
//此处参数为ApiInfo对象
//指定构建api文档的详细信息的方法
.apiInfo(apiInfo())
.select()
//指定构建api接口的包路径-指定具体包路径
// .apis(RequestHandlerSelectors.basePackage("com.provider.controller"))
//指定构建api接口的包路径-此处为所有包(未指定)
.apis(RequestHandlerSelectors.any())
//访问路径下面的接口
// .paths(PathSelectors.any())
// .paths(PathSelectors.ant("/libai/**"))
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//可根据url路径设置那些请求加入文档,忽略哪些请求
.paths(PathSelectors.any())
.build()
//分组管理可以与哪个访问路径结合使用
// .groupName("用户管理")
;
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
//界面标题
.title("Swagger2构建Restful API文档")
//接口描述
.description("后端API接口文档展示")
//联系方式,联系人-网址-邮箱
.contact(new Contact("name","https://xxx.com/libai","xxx@163.com"))
//版本信息
.version("1.0.0")
//证书描述
.license("访问主页")
//证书地址
.licenseUrl("xxx.com")
//系统服务网址
.termsOfServiceUrl("xxx.com")
.build();
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**")
.addResourceLocations("classpath:/static/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
}
}
4、常用注释
@Api(tags = “类业务名称”)
@ApiOperation(value = “接口名称”,notes = “接口描述”)
@ApiImplicitParams 注解是和 @ApiImplicitParam 注解配合使用的。
@ApiImplicitParams 注解描述的是一组请求参数,而单个请求参数是由@ApiImplicitParam注解来描述的。
name:参数名
value:参数解释
required:参数是否必须
dataType:参数类型
paramType:
- header:请求头
- query:?param=value的形式
- path:路径,Restful风格接口
- body:请求体
- form:以form表单的形式提交
@RestController
@RequestMapping("/parent")
@Slf4j
@RequiredArgsConstructor
@Api(tags = "类业务名称")
public class MyController {
private final HisController hisController;
@ApiOperation(value = "接口名称",notes = "接口描述")
@ApiImplicitParams(
@ApiImplicitParam(name = "createTime", value = "创建时间:yyyy-MM-dd", required = true, dataType = "String", paramType = "path") ,
@ApiImplicitParam(name = "endTime", value = "结束时间:yyyy-MM-dd", required = true, dataType = "String", paramType = "path")
)
@PostMapping("/child")
public void calc(String createTime,String endTime) {
log.info("====================================================");
log.info("开始xxxx");
try{
createTime = createTime + " 00:00:00";
hisController.fac(createTime);
}catch (Exception e){
log.error("/parent/child接口异常",e);
}
}
}
5、访问地址
bootstrapui访问地址:http://ip:port/context/doc.html
swagger-ui访问地址:http://ip:port/context/swagger-ui.html