您当前的位置:首页 > 电脑百科 > 程序开发 > 编程百科

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

时间:2021-09-08 15:24:09  来源:  作者:希留说

前言

前后端分离开发模式中,api文档是最好的沟通方式。今天就来说一说如何整合Swagger生成一套漂亮、美观、实用的接口文档。
源码传送门:
https://gitee.com/huoqstudy/xiliu-admin.git

一、Swagger介绍

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务,它有着如下的优点:
1. 及时性 (接口变更后,能够及时准确地通知相关前后端开发人员)
2. 规范性 (并且保证接口的规范性,如接口的地址,请求方式,参数及响应格式和错误信息)
3. 一致性 (接口信息一致,不会出现因开发人员拿到的文档版本不一致,而出现分歧)
4. 可测性 (直接在接口文档上进行测试,以方便理解业务)

二、配置Swagger

1. 添加依赖

<!--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
@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();
    }

}

3. 重启服务查看接口

访问路径:
http://localhost:8081/swagger-ui.html ,出现生成的文档页面。但是作为一个有审美追求的人,这ui也太难看了吧,果断放弃,更换成Knife4j

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

 

4. 使用Knife4j

Knife4j的前身是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
@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();

    }*/

}

4.3 重启服务查看接口

访问地址:
http://localhost:8081/doc.html,这个ui界面看起来就更美观,更符合国人的使用习惯。

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

 

5. 定义接口说明和参数说明

定义在类上:@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);
    }

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

 

总结

感谢大家的阅读,以上就是今天要讲的内容,本文简单介绍了如何整合Swagger生成api接口文档,虽然很多人喷Swagger,不好用,基于注解,代码入侵很强,等等 很多原因。但总体来看,swagger发展至今,包括在各个语言,NodeJs、.net、java、php等等,它可以说是一个有些接口规范的东西,从开始,到一步步规范,其实是一个很艰难的过程,任何事物,都不是尽善尽美的,swagger也是一样,至少它给这么多语言提供了一种文档生成的解决方案,其价值就远超它本身的缺点。

最后弱弱地问一句,你们的项目用swagger了吗?



Tags:api接口文档   点击:()  评论:()
声明:本站部分内容及图片来自互联网,转载是出于传递更多信息之目的,内容观点仅代表作者本人,如有任何标注错误或版权侵犯请与我们联系(Email:2595517585@qq.com),我们将及时更正、删除,谢谢。
▌相关推荐
前言前后端分离开发模式中,api文档是最好的沟通方式。今天就来说一说如何整合Swagger生成一套漂亮、美观、实用的接口文档。 源码传送门: https://gitee.com/huoqstudy/xiliu-...【详细内容】
2021-09-08  Tags: api接口文档  点击:(65)  评论:(0)  加入收藏
日常项目开发的过程中,接口文档是必不可少的。后端工程师与前端工程师之间需要接口文档来定义数据传输协议、系统对外暴露接口需要文档来说明、系统之间相互调用需要文档来记...【详细内容】
2019-10-23  Tags: api接口文档  点击:(200)  评论:(0)  加入收藏
▌简易百科推荐
摘 要 (OF作品展示)OF之前介绍了用python实现数据可视化、数据分析及一些小项目,但基本都是后端的知识。想要做一个好看的可视化大屏,我们还要学一些前端的知识(vue),网上有很多比...【详细内容】
2021-12-27  项目与数据管理    Tags:Vue   点击:(1)  评论:(0)  加入收藏
程序是如何被执行的&emsp;&emsp;程序是如何被执行的?许多开发者可能也没法回答这个问题,大多数人更注重的是如何编写程序,却不会太注意编写好的程序是如何被运行,这并不是一个好...【详细内容】
2021-12-23  IT学习日记    Tags:程序   点击:(9)  评论:(0)  加入收藏
阅读收获✔️1. 了解单点登录实现原理✔️2. 掌握快速使用xxl-sso接入单点登录功能一、早期的多系统登录解决方案 单系统登录解决方案的核心是cookie,cookie携带会话id在浏览器...【详细内容】
2021-12-23  程序yuan    Tags:单点登录(   点击:(8)  评论:(0)  加入收藏
下载Eclipse RCP IDE如果你电脑上还没有安装Eclipse,那么请到这里下载对应版本的软件进行安装。具体的安装步骤就不在这赘述了。创建第一个标准Eclipse RCP应用(总共分为六步)1...【详细内容】
2021-12-22  阿福ChrisYuan    Tags:RCP应用   点击:(7)  评论:(0)  加入收藏
今天想简单聊一聊 Token 的 Value Capture,就是币的价值问题。首先说明啊,这个话题包含的内容非常之光,Token 的经济学设计也可以包含诸多问题,所以几乎不可能把这个问题说的清...【详细内容】
2021-12-21  唐少华TSH    Tags:Token   点击:(9)  评论:(0)  加入收藏
实现效果:假如有10条数据,分组展示,默认在当前页面展示4个,点击换一批,从第5个开始继续展示,到最后一组,再重新返回到第一组 data() { return { qList: [], //处理后...【详细内容】
2021-12-17  Mason程    Tags:VUE   点击:(14)  评论:(0)  加入收藏
什么是性能调优?(what) 为什么需要性能调优?(why) 什么时候需要性能调优?(when) 什么地方需要性能调优?(where) 什么时候来进行性能调优?(who) 怎么样进行性能调优?(How) 硬件配...【详细内容】
2021-12-16  软件测试小p    Tags:性能调优   点击:(19)  评论:(0)  加入收藏
Tasker 是一款适用于 Android 设备的高级自动化应用,它可以通过脚本让重复性的操作自动运行,提高效率。 不知道从哪里听说的抖音 app 会导致 OLED 屏幕烧屏。于是就现学现卖,自...【详细内容】
2021-12-15  ITBang    Tags:抖音防烧屏   点击:(23)  评论:(0)  加入收藏
11 月 23 日,Rust Moderation Team(审核团队)在 GitHub 上发布了辞职公告,即刻生效。根据公告,审核团队集体辞职是为了抗议 Rust 核心团队(Core team)在执行社区行为准则和标准上...【详细内容】
2021-12-15  InfoQ    Tags:Rust   点击:(24)  评论:(0)  加入收藏
一个项目的大部分API,测试用例在参数和参数值等信息会有很多相似的地方。我们可以复制API,复制用例来快速生成,然后做细微调整既可以满足我们的测试需求1.复制API:在菜单发布单...【详细内容】
2021-12-14  AutoMeter    Tags:AutoMeter   点击:(20)  评论:(0)  加入收藏
最新更新
栏目热门
栏目头条