江苏龙网

  1. 主页 > 生活百科 > >

还在手写api接口文档？试试它吧

api接口文档

前言前后端分离开发模式中，api文档是最好的沟通方式 。今天就来说一说如何整合Swagger生成一套漂亮、美观、实用的接口文档 。
源码传送门：
https://gitee.com/huoqstudy/xiliu-admin.git
一、Swagger介绍Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务，它有着如下的优点：
1. 及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
2. 规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
3. 一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
4. 可测性 (直接在接口文档上进行测试，以方便理解业务)
二、配置Swagger1. 添加依赖<!--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>2. 创建Swagger2配置文件代码如下（示例）：
@Configuration@EnableSwagger2public class Swagger2Config {@Beanpublic 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();}}3. 重启服务查看接口访问路径：
http://localhost:8081/swagger-ui.html，出现生成的文档页面 。但是作为一个有审美追求的人，这ui也太难看了吧，果断放弃，更换成Knife4j

还在手写api接口文档？试试它吧

文章插图
 
4. 使用Knife4jKnife4j的前身是swagger-bootstrap-ui，前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目 。但是随着项目的发展,面对越来越多的个性化需求，不得不编写后端JAVA代码以满足新的需求，因此，项目正式更名为knife4j,取名knife4j是希望它能像一把匕首一样小巧、轻量，并且功能强悍，更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案，不仅仅只是专注于前端Ui前端 。
4.1 添加依赖需要删除原来引用的swagger依赖
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.0.7</version></dependency>4.2 修改配置类@Configuration@EnableSwagger2WebMvcpublic class Swagger2Config {@Bean(value = https://www.isolves.com/it/cxkf/bk/2021-09-08/"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;}/*@Beanpublic 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();}*/}4.3 重启服务查看接口访问地址：
http://localhost:8081/doc.html，这个ui界面看起来就更美观，更符合国人的使用习惯 。
还在手写api接口文档？试试它吧

文章插图
 
5. 定义接口说明和参数说明定义在类上：@Api
定义在方法上：@ApiOperation
定义在参数上：@ApiParam
@Api(tags = "用户管理")@RestController@RequestMApping("/ucenter/member")public class MemberController {@Autowiredprivate MemberService memberService;@ApiOperation(value = https://www.isolves.com/it/cxkf/bk/2021-09-08/"所有用户列表")@GetMapping(value = "/getAll")public List 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);}}


推荐阅读


上一篇：适合女人喝的养生茶有哪些,女人喝茶有哪些注意事项

下一篇：芍药花的功效,芍药花的功效与作用都有哪些