springboot2.x基础教程：Swagger详解给你的接⼝加上⽂档说明
相信⽆论是前端还是后端开发，都或多或少地被接⼝⽂档折磨过。前端经常抱怨后端给的接⼝⽂档与实际情况不⼀致。后端⼜觉得编写及维护接⼝⽂档会耗费不少精⼒，经常来不及更新。其实⽆论是前端调⽤后端，还是后端调⽤后端，都期望有⼀个好的接⼝⽂档。
SpringBoot集成Swagger能够通过很简单的注解把接⼝描述清楚，⽣成可视化⽂档页⾯。
原⽣的Swagger-ui界⾯很粗糙，这⾥⽤替代。
⼀个好的HTTP接⼝⽂档描述
写清楚接⼝的请求路径: QueryPath: /user/login
写清楚接⼝的请求⽅法类型： GET/POST/DELETE/PUT
写清楚接⼝的业务含义，使⽤场景
写清楚接⼝的⼊参：参数描述、参数类型、参数结构、参数是否必传
写清楚接⼝的返回类型：返回的数据结构，异常状况
SpringBoot集成Swagger
项⽬引⼊依赖
<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>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-ui</artifactId>
<version>2.0.4</version>
</dependency>
SpringBoot关于Swagger配置
把此Swagger配置粘⼊项⽬即可
@EnableSwagger2
@Configuration
public class SwaggerConfig implements WebMvcConfigurer {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//这⾥改成⾃⼰的接⼝包名
.apis(RequestHandlerSelectors.basePackage("dehome.ller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot教程接⼝⽂档")//标题
.description("使⽤swagger⽂档管理接⼝")//描述
.contact(new Contact("codehome", "", "dsyslove@163"))//作者信息
.version("1.0.0")//版本号
.build();
}
//解决doc.html，swagger-ui.html 404问题
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").addResourceLocations(
"classpath:/static/");
registry.addResourceHandler("swagger-ui.html").addResourceLocations(
"classpath:/META-INF/resources/");
registry.addResourceHandler("doc.html").addResourceLocations(
"classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations(
"classpath:/META-INF/resources/webjars/");
}
}
Swagger的具体使⽤
各个注解的作⽤
@Api 放在类上介绍类的作⽤
@ApiOperation 放在⽅法上介绍⽅法的作⽤
@ApiImplicitParam介绍⼊参说明
@ApiResponse介绍返回状态
@ApiModel、@ApiModelProperty介绍⼊参是对象，返回是对象字段说明
代码⽰例
@RestController
@Api(tags = "Swagger注解测试类")
public class SwaggerUserController {
@ApiOperation(value = "这是⼀个echo接⼝")
@ApiImplicitParams({
@ApiImplicitParam(name = "msg",value = "请求的msg参数",required = true,paramType = "query"),
@ApiImplicitParam(name = "token",value = "请求的token",required = false,paramType ="header" )
})
@ApiResponses({
@ApiResponse(code=200,message = "请求成功"),
@ApiResponse(code=400,message="请求⽆权限")
})
@GetMapping("/echo")
public String echo(String msg,@RequestHeader(name = "token") String token){
return msg;
}
@PostMapping("/login")
public R<UserInfoVO> login(@RequestBody LoginDTO loginDTO){
UserInfoVO userInfoVO=new UserInfoVO();
userInfoVO.setNickname("编程之家");接口文档怎么看
userInfoVO.setToken("xxx");
return R.ok(userInfoVO);
}
}
@Data
@ApiModel
public class LoginDTO {
@ApiModelProperty(value = "⽤户账号或者邮箱")
String account;
@ApiModelProperty(value = "⽤户密码")
String passwd;
@ApiModelProperty(value = "⽤户密码")
String verifyCode;
}
接⼝⽂档效果
这⾥访问的是localhost:8080/doc.html,knife4j-spring-ui还有相⽐原⽣还有更多强⼤的功能，⼤家⾃⾏发现。千⾥之⾏，始于⾜下。这⾥是SpringBoot教程系列第⼆篇，所有项⽬源码均可以在我的上⾯下载源码。