前后端分离开发模式中,api文档是最好的沟通方式。今天就来说一说如何整合Swagger生成一套漂亮、美观、实用的接口文档。
源码传送门:
https://gitee.com/huoqstudy/xiliu-admin.git
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务,它有着如下的优点:
1. 及时性 (接口变更后,能够及时准确地通知相关前后端开发人员)
2. 规范性 (并且保证接口的规范性,如接口的地址,请求方式,参数及响应格式和错误信息)
3. 一致性 (接口信息一致,不会出现因开发人员拿到的文档版本不一致,而出现分歧)
4. 可测性 (直接在接口文档上进行测试,以方便理解业务)
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
代码如下(示例):
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket apiConfig() {
return new Docket(DocumentationType.SWAGGER_2)
// 调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//大标题
.title("接口文档")
//详细描述
.description("接口文档")
//版本
.version("1.0")
//作者
.contact(new Contact("xiliu", "http://www.xxx.com", "277769738@qq.com"))
.build();
}
}
访问路径:
http://localhost:8081/swagger-ui.html ,出现生成的文档页面。但是作为一个有审美追求的人,这ui也太难看了吧,果断放弃,更换成Knife4j
Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目。但是随着项目的发展,面对越来越多的个性化需求,不得不编写后端JAVA代码以满足新的需求,因此,项目正式更名为knife4j,取名knife4j是希望它能像一把匕首一样小巧、轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端。
需要删除原来引用的swagger依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.7</version>
</dependency>
@Configuration
@EnableSwagger2WebMvc
public class Swagger2Config {
@Bean(value = "defaultApi2")
public Docket defaultApi2() {
Docket docket=new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder()
.title("接口文档")
.description("# 接口文档")
.termsOfServiceUrl("http://www.xx.com/")
.contact("277769738@qq.com")
.version("1.0")
.build())
//分组名称
.groupName("2.X版本")
.select()
//这里指定Controller扫描包路径
.apis(RequestHandlerSelectors.basePackage("com.java.xiliu"))
.paths(PathSelectors.any())
.build();
return docket;
}
/*@Bean
public Docket apiConfig() {
return new Docket(DocumentationType.SWAGGER_2)
// 调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//大标题
.title("接口文档")
//详细描述
.description("接口文档")
//版本
.version("1.0")
//作者
.contact(new Contact("xiliu", "http://www.xxx.com", "277769738@qq.com"))
.build();
}*/
}
访问地址:
http://localhost:8081/doc.html,这个ui界面看起来就更美观,更符合国人的使用习惯。
定义在类上:@Api
定义在方法上:@ApiOperation
定义在参数上:@ApiParam
@Api(tags = "用户管理")
@RestController
@RequestMApping("/ucenter/member")
public class MemberController {
@Autowired
private MemberService memberService;
@ApiOperation(value = "所有用户列表")
@GetMapping(value = "/getAll")
public List<Member> list(){
return memberService.list(null);
}
@ApiOperation(value = "根据id删除用户")
@PostMapping(value = "del/{memberId}")
public boolean deleteById(
@ApiParam(name = "memberId", value = "用户ID", required = true)
@PathVariable Long memberId){
return memberService.removeById(memberId);
}
@ApiOperation(value = "保存用户")
@PostMapping(value = "save")
public boolean save(
@ApiParam(name = "member", value = "用户对象json", required = true)
@RequestBody Member member){
if (null == member.getMemberId()) {
return memberService.save(member);
}
return memberService.updateById(member);
}
}
感谢大家的阅读,以上就是今天要讲的内容,本文简单介绍了如何整合Swagger生成api接口文档,虽然很多人喷Swagger,不好用,基于注解,代码入侵很强,等等 很多原因。但总体来看,swagger发展至今,包括在各个语言,NodeJs、.net、java、php等等,它可以说是一个有些接口规范的东西,从开始,到一步步规范,其实是一个很艰难的过程,任何事物,都不是尽善尽美的,swagger也是一样,至少它给这么多语言提供了一种文档生成的解决方案,其价值就远超它本身的缺点。
最后弱弱地问一句,你们的项目用swagger了吗?