最美的在线接口文档knife4j,使用apipost工具快速生成在线接口文档

背景

开发最不想干的事是什么？那一定是写文档，相对于敲代码，写文档实在是太难了，尤其是接口文档。那么有需求，就有市场，于是就有Swagger应运而生，不止于此，相伴而生的还有了很多基于Swagger的接口ui界面面，比如Swagger ui，SwaggerBootstrap UI，knife4j等。那么其中最美的当然是今天我们的主角knife4j，没有之一。那么我们就直接上干货吧！

优点

1. 采用左右布局，更符合我们的审美，操作方便

2. 一键复制接口，复制文档，复制接口地址

3. 自动生成请求样例报文，及返回报文

4. 注解可以自动注入参数说明及填写要求

5. 集成简单

环境

1. jdk1.8+

2. springboot 2.5.6

3. knife4j 2.0.4

搭建

pom文件引入依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.4</version></dependency>

定义配置类

@Configuration@EnableSwagger2public class SwaggerConfig {
    /**
     * Swagger2 API
     * @author: liyajie
     * @date: 2021/2/19 16:08
     * @param
     * @return: springfox.documentation.spring.web.plugins.Docket
     * @exception:
     * @update:
     * @updatePerson:
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(this.apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lyj.knife4j"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * API 接口描述
     * @author: liyajie
     * @date: 2021/2/19 16:08
     * @param
     * @return: springfox.documentation.spring.web.plugins.Docket
     * @exception:
     * @update:
     * @updatePerson:
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .contact("李亚杰<17710557864@163.com>")
                .title("RestAPI文档")
                .description("RestAPI文档")
                .version("1.0.0-DEV")
                .build();
    }}

常用注解

1. @Api：用在controller类上，主要标明接口api一级分类名称

image.png

2. @ApiOperation：用在方法上，主要标明接口api名称

image.png

3. @ApiModel：用在入参dto类上，主要是标明参数类的名称

image.png

4. @ApiModelProperty: 用在参数dto类的属性上，主要是标明dto属性的说明及样例

image.png

测试

启动项目后，访问地址http://ip:port/doc.html即可

image.png

注意点

现在流行的springboot集成knife4j时一定要注意版本的兼容问题，比如小编开始使用时，springboot的版本是2.6.2，然后knife4j的版本是2.0.4，配置完成后项目就启不来了。所以版本兼容很重要！

ApiPost是一个支持团队协作，并可直接生成文档的API调试、管理工具。它支持模拟POST、GET、PUT等常见请求，是后台接口开发者或前端、接口测试人员不可多得的工具 。

使用者不仅可以利用apiopst调试接口，还可以书写相关注释（接口文档），方便的生成可读性好、界面美观的在线接口文档。

本文主要包含以下内容：

介绍ApiPost工具，它能做什么下载、安装的方法一些常用的操作介绍一些使用技巧

前言：apipost能做什么？

ApiPost是一个支持团队协作，并可直接生成文档的API调试、管理工具。它可以像postman那样支持模拟POST、GET、PUT等常见请求也可以快速生成接口文档，是后台接口开发者或前端、接口测试人员不可多得的工具 。首先看下它的界面风格。

下载、安装apipost

ApiPost安装下载十分简单，在官网（自行百度）直接下载对应操作系统的安装包（支持window、mac、linux）安装即可，官网也提供了丰富的安装文档，这里不再赘述了。

ApiPost支持常见的接口发送、文档生成等。作为一名开发者，相信你从上面截图就可以基本看出来它的使用方法。这里主要介绍一些其他的常见操作。不过初次使用的时候，需要先注册一个账号，创建一个项目，然后点击左侧的 APIS 菜单栏就进到控制台了。

以下图是针对目录的常用操作

总之使用基本很简单，你下载安装一看就会了，实在有问题可以去官网查看文档或者去社区提问。

一些操作技巧

小技巧之：快速导入参数

apipost支持多种格式的参数导入，见下图，你再也不用一个一个参数的慢慢写了：

导入格式支持key-value和json格式：

1-1：key-value格式导入示例：

key-value格式常见的就是浏览器（F12）控制台的数据格式，见下图：

我们，复制以上请求头参数，然后粘贴到apipost，点击导入

参数则瞬间导入到了请求参数中，见下图：

以上示例只是展示了如何快速导入到header参数，其他参数比如query、body操作方式是一模一样滴。

1-2：json格式导入示例：

apipost也支持json格式的参数导入，参数格式可以如下：

{ "id": 123, "title": "我是标题"}

如图，点击导入，参数也快速导入到了请求参数中。

小技巧之：参数注释自动识别

上面我们写了如何快速导入参数，其实对于生成接口文档来说，参数描述（注释）才是最要命的，对于我们一直忙碌的程序员，花大量时间用在写文档上实在太累！

好在apipost帮我们节省了很多时间，一个参数，只要写过一次注释，下次遇到同样的参数直接选中就行。举例：

在上图中，我们针对id和title写了对应的注释：

id：“我是文章Id”title：“我是文章标题”

当我们新建一个接口的时候，假如这个接口同样用到了id或者title

等参数，点击参数描述就会呈现出刚刚输入过的参数描述，直接选中即可，不用再麻烦的打字输入了。

这个小功能是不是节约了开发小伙伴很多时间呢？

小技巧之：快速定位当前接口目录

左侧的目录默认都是闭合的，有时候我们不知道当前正在编辑的接口属于哪个目录，找起来相当头疼。apipost提供了“定位到当前接口目录” 功能（见下图），可以快速打开当前正在编辑的接口、文档所在的目录，是不是解决了您的大问题了呢？

其实，apipost还有很多很多更加符合中国人操作习惯的小功能，等待您去发现。

小技巧之：生成并分享在线接口文档

说了这么多，好像还没说到重点，apipost怎么生成接口文档呢？很简单：新版ApiPost支持分享单个项目、也支持分享单个目录或者文档：

支持设置文档链接的有效期：

支持设置文档的查看权限：

小TIPS：apipost 导出文档响应为空？

很多小伙伴问，为什么apipost 导出文档响应为空？那是因为你么有添加响应示例。

ApiPost生成的文档怎么添加响应示例？很简单：

小技巧之：快速克隆一个项目

有时候我们需要复制一个项目的数据，ApiPost如何克隆（复制）一个项目？

很简单：

小技巧之：resful风格的接口的路径变量

类似这样风格的接口：

http://example.com/api/users/1 //GET 获取标识为1用户信息

ApiPost支持把像这样的restful风格链接中的uid也就是1作为参数单独提出来比较方便调试和解释。

只需要把URL路径中的ID设置为

:变量名

即可。

这样的话，我们生成的文档就会类似：