Swagger2
Swagger能够根据代码中的注解自动生成api文档,并且提供测试接口;
引入依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
配置文件
package cn.wolfcode.luowowo.swagger2;
import ...;
@Configuration
@EnableSwagger2
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()
// 扫描的包路径
.apis(RequestHandlerSelectors.basePackage("主类包的路径, 例如: cn.xxxx.xx"))
// 定义要生成文档的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/");
}
}
访问地址
http://localhost:8080/swagger-ui.html
常用标签
@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
有些接口不想显示,就贴上去,可以贴在类上,也可以贴在方法上。