文档即服务：一款与众不同的接口设计工具

我在春假假期期间，开发了一款提升开发效率和质量的接口设计工具。

如果你是做架构、后端开发、前端开发或者测试，那么这个工具将会是帮助你提升开发质量和效率的神器。

为什么要开发Panda Api?

Panda Api主要要解决的一个问题是如何在定义好接口文档，后端不写一行代码的情况下，就能为前端开发提供接口服务。

传统的开发，接口需要等待后端漫长的开发，前端开发过程中经常会因为后端开发的重新编译、服务重启、调Bug等原因，服务频繁的挂掉，无法继续开发，需要等待后端服务的启动；后端要进行某些功能的测试，也要等待前端的开发完成，开发过程中相互等待、两边相互影响，非常的影响开发状态和效率。

有时候，我们的产品经理，或者客户提出一个新的需求，需要快速修改代码去实现验证，一次简单前端的修改就要经过长时间等待等待后端开发完成，走一遍完整的修改，调整，测试，部署，发布流程来测试某个修改调整，这种改一行等几十分钟的开发方式对效率的拖累是极其恐怖的。 用Panda Api就不会存在这样的问题，Panda Api符合MVP开发理论，而且完全不经过后端开发，完成所有的功能，修改。

很多的接口设计工具，要么只是方便后端提供的一个工具，比如Swagger，或者是前端的工具，比如Hapi，或者就是一个测试工具，比如Postman，PostWoman。 我理解的接口设计文档，应该是属于产品经理、后端开发、前端开发、测试等人所达成的一个共识，应该是参与开发和测试的人一起去维护的一个文档。并且这个文档应该是提升开发效率和质量，而不是去增加工作负担。

因此，我决定去开发一个工具，只要做好接口的设计，就自动的有：接口文档自动生成、接口服务提供、后端接口测试等

写一个接口文档

Panad Api 进行接口设计使用json5语法，和json很像，但是比json更简单，支持注释、字符串换行等，一个用户登录的接口：它写起来来像这样：

// auth.json5
{
    name:"用户登录和退出",
    apis:
    [{
        name:"用户登录",
        desc:"如果用户登录成功，会获得一个token",
        method: "POST",
        url:"/login/",
        body_mode:"json",
        body:{
            username:{name: "用户名"},
            password:{name: "密码"}
        },
        response:{
            code:{name:"登录结果状态码", type:"int", $enum:[[-1, "失败"], [1, "成功"]]},
            msg:{name:"登录结果说明", type:"cstring"},
            token:{name:"用户token" desc:"登录成功后才会有token", type:"string", required:false, length:64}
        },
        test_data:[
            {
                body:{username:"edison", password:"123"},
                response:{code:-1, msg:"密码不正确"}
            },
            {
                body:{username:"lily", password:"123"},
                response:{code:-1, msg:"用户不存在"}
            },
            {
                body:{username:"root", password:"123"},
                response:{code:1, msg:"登录成功", token:"5lCadRru(ADn2IE!$LV%x%JF3JNmz*Nf5nFieUG!r((&esi2CLI$jb!227Lh"} 
            }
        ]
    },
    ...
]}

查看在线文档

这就是我们的接口文档，写好这个文档后，我们在文档目录运行:panda命令，就可以访问http://localhost:9000查看在线文档了。

Panda Api在线文档

这个在线文档已经非常方便查看接口的各个信息，并可以在线点击进行后端接口测试。不过，它的杀手锏是为前端提供接口服务。

请求接口

我们可以请求接口http://localhost:9000/login/，使用test_data里面的第一组的body数据请求/login/接口：

curl localhost:9000/login/ -X POST -H "Content-Type:application/json" -d '{"username":"edison","password":"123"}'
{"code":-1,"msg":"密码输入不正确"}

获得同一组的response数据。

test_data中，body和response的数据是一一对应的，只要请求的是body中的数据，就会返回response中的数据。这会非常方便我们前端模拟各种后端返回的状况然后进行前端调试。

请求第二组：

curl localhost:9000/login/ -X POST -H "Content-Type:application/json" -d '{"username":"lily","password":"123"}'
{"code":-1,"msg":"用户名不存在","token":"5lCadRru(ADn2IE!$LV%x%JF3JNmz*Nf5nFieUG!r((&esi2CLI$jb!227Lh"}

请求第三组：

curl localhost:9000/login/ -X POST -H "Content-Type:application/json" -d '{"username":"root","password":"123"}'
{"code":1,"msg":"登录成功"}

mock自动生成

让我们请求的不是test_data中的数据，Panda Api会根据文档中response的定义，自动返回mock数据。

curl localhost:9000/login/ -X POST -H "Content-Type:application/json" -d '{"username":"hello","password":"123"}'
{"code":-1,"msg":"理制名务在斗日来传海持问次展；"}

curl localhost:9000/login/ -X POST -H "Content-Type:application/json" -d '{"username":"hello","password":"123"}'
{"code":1,"msg":"又温书元往目号法局器飞证它声有现按，","token":"eUYWe7cziBco~NqALBVc4kOLQTs~naBtQmri4G3erdAqdQVSgn!1Ix(B&Hvf"}

还可以对test_data进行部分mock数据返回，比如我们想让用户名和密码输入正确的数据返回动态的token，这么这么写test_data电数据：

{
    body:{username:"root", password:"123"},
    response:{code:1, msg:"登录成功", token:{$mock:true, required:true}}
}

我们把test_data中的token标记为使用mock自动生成，同时重写了response中的定义，把required属性改为了true，这个时候我们用数据{username:"root", password:"123"}请求接口，就会得到动态的token数据返回。

还可以使用在线文档进行接口测试

Panda Api

就这样，简简单单，一份在线文档和一个前端可使用的接口服务，以及测试后端的接口服务就完成。

支持数组和对象这样的复杂结构

除了简单的字段，Panda Api也支持复杂的数据结构的请求body和response，比如，返回一个文章列表的response可以这么写：

response:{
    total_page: {name:"total page", type:"number"},
    current_page: {name:"current page num", type:"number"},
    result: 
        [{
            id:{name:"文章Id", type:"PosInt"},
            title:{name:"文章标题"},
            category:{
                id:{name:"分类iD"},
                name:{name:"分类名称"}
            },
            author_name:{name:"作者名称"},
            tags:[{
                id:{name:"Tag id", type:"PosInt"},
                name:{name:"标签名称"}
            }],
            created:{name:"article created time", type:"timestamp"}
        }]
}

result是一个对象列表，列表中是以一个对象，直接用[]包括起来就可以了。

category是一个对象，直接写对象的属性id和name。

tags是一个对象列表，列表中是tag对象。

在语法设计的时候，我尽量让我们可以用足够简单清晰的语法来表达。

继承重用相同的数据模型

虽然上述的功能已经可以满足很多需求，但有时候一个同样的数据模型，需要在多个接口中重复使用，如果每个地方都写一篇，写起来很麻烦，维护起来更麻烦。Panda Api支持我们对数据模型的继承重用。

比如文章模型在添加、列表、查看等接口都需要用到，我们可以把文章的数据模型放到_data/models.json5中，然后在每个需要的地方进行调用。

// _datat/models.json5
{
Article:{
    id:{name:"文章Id", type:"PosInt"},
    title:{name:"文章标题"},
    category:{
        id:{name:"分类iD"},
        name:{name:"分类名称"}
    },
    author_name:{name:"作者名称"},
    tags:[{
        id:{name:"Tag id", type:"PosInt"},
        name:{name:"标签名称"}
    }],
    created:{name:"article created time", type:"timestamp"}
}
}

继承到body进行重用

比如文章添加接口的body，我们想做这么几件事情：

我们可以这么来重用：

body: {
    $ref:"./_data/models.json5:Article",
    $exclude:["created", "category/name", "tags/0/name"],
    id:{name:"文章Id", type:"PosInt", required:false},
}

继承到response进行重用

比如：文章列表接口的response，我们想做这么几件事情：

我们可以这么来重用：

response: {
    $ref:"./_data/models.json5:Article",
    $include:["id", "title", "category", "created"],
    $exclude:["category/id"]
}

继承整个接口进行重用

我们也可以整个接口的复用，然后再进行修改。和模型继承差不多，限于篇幅这里就不展开

文档的团队协作和版本控制

因为Panda Api写出来的文档是json5和markdown格式的文档，所以接口文档可以用Git, Mercuria等版本控制工具进行版本管理和多人协作维护，非常的方便。

Panda Api的其它功能

Panda Api 还提供了Auth的接口认证服务、后端接口测试、全局字段设置、多服务器接口配置、多版本接口、纯markdown文档编写、多级文档目录等功能。更多在Panda Api的中文文档里面。

最初我在设计这个工具的时候，只是想解决自己在律品团队开发过程中的疼痛点，在逐步开发完善，工具越来越好用， 就想把这个工具开源出来，为所有有这个需求和痛点的开发者、开发团队使用。让每个人都能使用它，收集大家使用的反馈意见，把工具做得更好。

Panda Api的项目地址：

https://github.com/arlicle/panda-api

Panda Api中文文档地址：

https://www.debugmyself.com/p/2020/1/24/panda_api_read_me/

如何使用Panda APi?

Panda Api使用Rust语言开发，提供了强大的性能和稳定性。同时，程序编译为直接运行的安装包，下载对应操作系统的安装包，直接点击运行安装即可，无需安装环境，也不用进行编译。提供了Mac、Linux、Windows版本。

欢迎大家使用和提意见讨论。谢谢；）

2020-02-23 02:56

上一篇: 使用webhooks完成自动部署
下一篇:Panda Api纯文档编写和多级菜单目录文档

留言