官网:springboot集成knife4j
swapper2
Swagger能够根据代码中的注解自动生成api文档,并且提供测试接口;
依赖
<!--swagger2的依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
</dependency>
<!--swagger2视图-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
</dependency>
配置
@Configuration
@EnableSwagger2 //开启swagger2的功能
public class SwaggerConfig implements WebMvcConfigurer {
@Bean
public Docket productApi() {
//添加head参数start
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<Parameter>();
tokenPar.name("token").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
pars.add(tokenPar.build());
return new Docket(DocumentationType.SWAGGER_2).select() //创建一个swagger2的文档
// 扫描的包路径(controller的路径)
.apis(RequestHandlerSelectors.basePackage("cn.swag.demo.controller"))
// 定义要生成文档的Api的url路径规则
.paths(PathSelectors.any())
.build()
.globalOperationParameters(pars)
// 设置swagger-ui.html页面上的一些元素信息。
.apiInfo(metaData());
}
private ApiInfo metaData() {
return new ApiInfoBuilder()
// 标题
.title("SpringBoot集成Swagger2")
// 描述
.description("项目接口文档")
// 文档版本
.version("1.0.0")
.license("Apache License Version 2.0")
.licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
.build();
}
//ui页面
@Override //添加静态资源
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
常用注解
@Api/@ApiOperation
用法说明:
@Api:用在类上,说明该类的作用
@Api(value = "用户资源",description = "用户资源控制器")
@ApiOperation:用在方法上,说明方法的作用
@ApiOperation(value = "注册功能",notes = "其实就是新增用户")
@ApiImplicitParams/@ApiImplicitParam
用法说明:
@ApiImplicitParams:用在方法上包含一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
paramType:参数放在哪个地方
header-->请求参数的获取
query-->请求参数的获取
path-->请求参数的获取(用于restful接口):
body-->请求实体中
@ApiImplicitParams({
@ApiImplicitParam(value = "昵称",name = "nickName",dataType = "String",required = true),
@ApiImplicitParam(value = "邮箱",name = "email",dataType = "String",required = true),
@ApiImplicitParam(value = "密码",name = "password",dataType = "String",required = true)
})
@ApiModel/@ApiModelProperty
用法说明
@ApiModel:描述一个Model的信息,也就是贴在实体类上
(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:描述一个model的属性 //贴在属性上
@ApiModel(value="用户",description="平台注册用户模型")
@ApiModelProperty(value="昵称",name="nickName",dataType = "String",required = true)
@ApiResponses/@ApiResponse
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息(200相应不写在这里面)
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出的异常类
@ApiResponses({
@ApiResponse(code=200,message="用户注册成功")
})
@ApiIgnore
有些接口不想显示,就贴上去,可以贴在类上,也可以贴在方法上。