你写的api接口代码真是_panda-api: Panda api 是一款接口设计工具，它能够生成文档、提供接口模拟服务(在你没写任何代码之前)、自动测试后端接口，有效提升项目的开发效率和质量...
panda-api | 中文文档
大量使用说明，教程在中文文档中，请大家先看看中文文档和相关例子，忙于开发，等时间充足再写英文文档。
Panda api makes it easier to build better api docs more quickly and easy for front end and back end.
Panda api encourages test driven development. it takes care of much of the hassle of web development between front end and back end, when you write done your api docs, you can focus on writing front end without needing to develop the backend. It’s free and open source.
Why Panda Api：
A better online read api docs.
Use json5 to write the api docs，eazy to lean and write.
Manage you api docs change as your code with git.
You can use Panda api as a back end api service with out backend develop.
Panda api takes test data helps developers auto test back end and front end
Suport define test case data
Mork data auto created
Environment route support, you can change the back end on panda api to development, test, production
Websocket support
Install
use installer (Recommended)
It looks like you’re running macOS, Linux, or another Unix-like OS. To download installer and install Panda api.
Install by Source code
Get the latest development version
git clone https://github.com/arlicle/panda-api.git
build and run panda api use cargo
cargo run
Once Panda Api is installed (see Install above) do this in a terminal:
panda --help
You should see the Panda Api command manual page printed to the terminal. This information includes command line options recognized by panda.
Getting started
Let's build a simple project to get our feet wet. We'll create a new directory, say my-project, and a file in it, auth.json5:
mkdirmy-project
cdmy-project
touchauth.json5
write a panda api doc
Edit the file auth.json5 with the following contents:
{
name:"Auth",
desc:"user login and logout",
order:1,
apis:
[{
name:"user login",
desc:"if user login success, will get a token",
method: "POST",
url:"/login/",
body_mode:"json", // form-data, text, json, html, xml, javascript, binary
body:{
username:{name: "username"},
password:{name: "password"}
},
response:{
code:{name:"response result code", type:"int", desc:"success is 1", enum:[-1, 1]},
msg:{name:"response result message", type:"string"},
token:{name:"login success, get a user token; login failed, no token", type:"string", required:false}
},
test_data:[
{
body:{username:"edison", password:"123"},
response:{code:-1, msg:"password incorrect"}
},
{
body:{username:"lily", password:"123"},
response:{code:-1, msg:"username not exist"}
},
{
body:{username:"root", password:"123"},
response:{code:1, msg:"login success", token:"fjdlkfjlafjdlaj3jk2l4j"}
}
]
},
{
name:"user logout",
method:"GET",
url:"/logout/",
query:{
id:{name:"user id"},
username:{}
},
response:{
code:{name:"response result code", type:"int", desc:"success is 1", enum:[-1, 1]},
msg:{name:"response result message", type:"string"}
},
test_data:[
{
query:{id:1, username:"root"},
response:{code:1, msg:"logout success"}
},
{
response:{code:-1, msg:"error"}
},
{
query:{id:3, username:"lily"},
response:{code:-1, msg:"username and id not match"}
}
]
}
]}
run command panda in the my-project
panda
You should see run info:
INFO actix_server::builder > Starting 8 workers
INFO actix_server::builder > Starting "actix-web-service-127.0.0.1:9000" service on 127.0.0.1:9000
view online api docs
Now we can view the api docs online http:://127.0.0.1:9000 or http://localhost:9000
Notice if you get a error
Error: Os { code: 48, kind: AddrInUse, message: "Address already in use" }
It's mean the port 9000 is in use, you need to change another one.
panda -p 9001
request the api
When the panda is running, we can request api in the docs without write a code of backend.
we request the api /login/ with test_data in the docs auth.json5.
1th:
curl localhost:9000/login/ -X POST -H "Content-Type:application/json" -d '{"username":"edison","password":"123"}'
// you will get response
{"code":-1,"msg":"password incorrect"}
2th:
curl localhost:9000/login/ -X POST -H "Content-Type:application/json" -d '{"username":"lily","password":"123"}'
// you will get response
{"code":-1,"msg":"username not exist"}
3th:
curl localhost:9000/login/ -X POST -H "Content-Type:application/json" -d '{"username":"root","password":"123"}'
// you will get response
{"code":1,"msg":"login success"}
If you request data not defined in the test_data, You will get a mock response
curl localhost:9000/login/ -X POST -H "Content-Type:application/json" -d '{"username":"hello","password":"123"}'
// you will get response like this
{"code":1,"msg":"SqM!3Mky@)q1O","token":"OkkdvtKKl(htx#KU6"}
Pretty simple, right?
mock options can help the mock data more like the production environment, update api /login/ response define:
...
response:{
code:{name:"response result code", type:"int", desc:"success is 1", enum:[-1, 1]},
msg:{name:"response result message", type:"sentence"}, // update type string to sentence
token:{name:"login success, get a user token; login failed, no token", type:"string", required:false, length:64} // set the token length:64
},
...
request data not defined in the test_data again:
curl localhost:9000/login/ -X POST -H "Content-Type:application/json" -d '{"username":"hello","password":"123"}'
// you will get response like this
{"code":1,"msg":"Qphxw ddfcvpy odpi ikdd, ","token":"PRL3%S%Uc&33X%HB*Yflc3qQt(LnC)cf6^0w357F07r3xUyafsvS#mr8BZw6UrMo"}
array and object field
response:{
total_page: {name:"total page", type:"number"},
current_page: {name:"current page num", type:"number"},
result:
[{
id:{name:"Article ID", type:"PosInt"},
title:{name:"Article title"},
category:{
id:{name:"category id"},
name:{name:"category name"}
},
author_name:{name:"Author name"},
tags:[{
id:{name:"Tag id", type:"PosInt"},
name:{name:"tag name"}
}],
created:{name:"article created time", type:"timestamp"}
}]
}
inherit model
mkdir_data
cd_data
touchmodels.json5
// _datat/models.json5
{
Article:{
id:{name:"Article ID", type:"PosInt"},
title:{name:"Article Title"},
category:{
id:{name:"Category ID",},
name:{name:"Category Name"}
},
author_name:{name:"Author name"},
tags:[{
id:{name:"Tag id", type:"PosInt"},
name:{name:"Tag name"}
}],
created:{name:"article created time", type:"timestamp"}
}
}
body: {
$ref:"./_data/models.json5:Article",
$exclude:["created", "category/name", "tags/0/name"],
id:{name:"Article ID", type:"PosInt", required:false},
}
response: {
$ref:"./_data/models.json5:Article",
$exclude:["created", "category/name", "tags/0/name"],
id:{name:"Article ID", type:"PosInt", required:false},
}
Examples
Panda Api 如何使用