什么是接口文档？
在实际的项目开发中，我们现在的web项目基本都是采用前后端分离的思想进行开发的，作为前端开发人员的你只需要用关心前端的代码，不用操心服务器，比如使用vue搭建一个UI界面,剩下的，我们就只需要一套AP接口就可以向服务器拿到数据，然后将拿到的数据遍历渲染到页面上的各个角落。
一个项目不是靠一个人来完成，而是一个团队。而应用程序的开发，需要的便是由前后端工程师共同定义的接口文档，编写接口文档，之后大家根据这个接口文档进行开发，一直到项目结束前都要一直维护。
一个web项目会分成前端和后端,前端发起一个Ajax请求，后端响应JSON数据回来，在这一过程中，我们要事先定义好一些东西，前端要提供给后端什么样的数据，而后端又会响应什么样的数据，前端和后端充分交流才是方便后期维护协作。
API接口文档长啥样？
编写接口文档五大要素：接口说明、请求方式、请求URL、请求参数、返回参数、等等、
具体例子：以微信小程序开发文档之小程序直播间接口为例子
总结：其实接口文档就是一份说明书
如何编写一份好看又整洁的接口文档？其实就是写一份得心应手的说明书，因为我们的接口文档是给别人看的。
这里推荐使用md语法动手编写说明书,直接用浏览器就可以看。
先来看下效果：
markdown代码：没办法粘贴，因为简书就是md语法......
有了参考文档，接下来我们就需要去用代码实现了。
案例演示：
案例实现：既要编写前端的代码，又需要编写后端的代码。
案例需求：koa2项目+ajax+json(不用数据库)+vue(采用脚本引入的vue取代前端模板引擎，就不搭脚手架了)
准备30条json数据:
效果预览：
前端代码：vue+ajax
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<script src="./javascripts/vue.js" type="text/javascript" charset="utf-8"></script>
<link rel="stylesheet" type="text/css" href="./stylesheets/style.css" />
</head>
<body>
<div id="app">
<div id="header">
<h2>90Sport | 体育</h2>
</div>
<div id="pos">
<div id="content" v-for="(item) in SportsList" :key="item.id">
<div class="box">
<p>{{item.title}}</p>
<div class="comment">评论：{{item.comment}}</div>
</div>
<div class="imageBox">
<img :src="item.image">
</div>
</div>
</div>
</div>
<script type="text/javascript">
const app = new Vue({
data() {
return {
SportsList: []
}
},
mounted() {
this.getMsg()
},
methods: {
getMsg: function() {
const app = document.getElementById('app')
const xhr = new XMLHttpRequest()
let that = this
xhr.onload = function() {
if (xhr.status == 200) { //判断状态码
//console.log(xhr.responseText
let data = JSON.parse(xhr.responseText) //用data接收服务器响应回来的json数据
if (data.errCode == 0) { //判断证明一下是不是ok状态
console.log(data.sportsList)
that.SportsList = data.sportsList
console.log(that.SportsList)
}
}
}
xhr.open('POST', '/sportsList', true) //发送POST请求，请求URL,开启异步加载
xhr.setRequestHeader('Content-Type', 'application/json') //设置请求头信息,json何使
xhr.send(JSON.stringify({
"page": 0,
"count": 10
})) //转义json数据
}
}
}).$mount('#app')
</script>
</body>
</html>
后端代码：koa框架
const router = require('koa-router')()
const fs = require('fs')
router.post('/sportsList', async (ctx ,next) => {
//指定字段类型
const args = [
{
field: 'page',
type: 'number'
},
{
field: 'count',
type: 'number'
}
]
let body = ctx.request.body
//处理浏览器请求的错误反馈
for(let i = 0;i<args.length;i++){//判断浏览器传递的参数
let item = args[i]
if(!Object.keys(body).includes(item.field)){//如果浏览器传递过来的请求字段不符合我们这里定义的字段，给它一个报错提醒
ctx.body = {
errCode: -1,
errMsg:'参数个数错误'
}
return
}else {
if(typeof body[item.field] != item.type){//判断浏览器传递的参数类型
ctx.body = {
errCode:-2,
errMsg:'参数类型错误'
}
return
}
}
}
let data = fs.readFileSync('./data/sportsList.json') //读取我们编写好的json数据
data = JSON.parse(data) //转义Json数据
let sportsList = data.splice(body.page * body.count,body.count) //决定起始位置和决定截取的个数
ctx.body = {
errCode:0,
errMsg: 'ok',
sportsList //响应'成功'信息
}
})
module.exports = router
JSON数据：
[
{
"id": 1,
"title": "英超-曼联轮换10人1-2莱斯特，青木球王破门，曼城提前3轮夺冠",
"image": "/images/1000.png",
"comment": 55
},
{
"id": 2,
"title": "湖人加时复仇尼克斯！浓眉20分塔克三分准绝杀 罗斯空砍27＋6＋6",
"image": "/images/1001.png",
"comment": 1159
},
{
"id": 3,
"title": "荷兰巨大损失！范戴克亲口宣布不参加欧洲杯！重伤缺战已7个月",
"image": "/images/1002.jpg",
"comment": 3342
},
{
"id": 4,
"title": "奇兵！马修斯绝平补篮＋塔克三分准绝杀 湖人加时险胜需谢他们",
"image": "/images/1004.png",
"comment": 3255
},
{
"id": 5,
"title": "科比生前和乔丹最后一次对话内容曝光，两人互发短信＋科教练发狠",
"image": "/images/1005.jpg",
"comment": 189
},
{
"id": 6,
"title": "英超-曼联轮换10人1-2莱斯特，青木球王破门，曼城提前3轮夺冠",
"image": "/images/1000.png",
"comment": 55
},
{
"id": 7,
"title": "湖人加时复仇尼克斯！浓眉20分塔克三分准绝杀 罗斯空砍27＋6＋6",
"image": "/images/1001.png",
"comment": 1159
},
{
"id": 8,
"title": "荷兰巨大损失！范戴克亲口宣布不参加欧洲杯！重伤缺战已7个月",
"image": "/images/1002.jpg",
"comment": 3342
},
{
"id": 9,
"title": "奇兵！马修斯绝平补篮＋塔克三分准绝杀 湖人加时险胜需谢他们",
"image": "/images/1004.png",
"comment": 3255
},
{
"id": 10,
"title": "科比生前和乔丹最后一次对话内容曝光，两人互发短信＋科教练发狠",
"image": "/images/1005.jpg",
"comment": 189
},
{
"id": 11,
"title": "英超-曼联轮换10人1-2莱斯特，青木球王破门，曼城提前3轮夺冠",
"image": "/images/1000.png",
"comment": 55
},
{
"id": 12,
"title": "湖人加时复仇尼克斯！浓眉20分塔克三分准绝杀 罗斯空砍27＋6＋6",
"image": "/images/1001.png",
"comment": 1159
},
{
"id": 13,
"title": "荷兰巨大损失！范戴克亲口宣布不参加欧洲杯！重伤缺战已7个月",
"image": "/images/1002.jpg",
"comment": 3342
},
{
"id": 14,
"title": "奇兵！马修斯绝平补篮＋塔克三分准绝杀 湖人加时险胜需谢他们",
"image": "/images/1004.png",
"comment": 3255
},
{
"id": 15,
"title": "科比生前和乔丹最后一次对话内容曝光，两人互发短信＋科教练发狠",
"image": "/images/1005.jpg",
"comment": 189
},
{
"id": 16,
"title": "英超-曼联轮换10人1-2莱斯特，青木球王破门，曼城提前3轮夺冠",
"image": "/images/1000.png",
"comment": 55
},
{
"id": 17,
"title": "湖人加时复仇尼克斯！浓眉20分塔克三分准绝杀 罗斯空砍27＋6＋6",
"image": "/images/1001.png",
"comment": 1159
},
{
"id": 18,
"title": "荷兰巨大损失！范戴克亲口宣布不参加欧洲杯！重伤缺战已7个月",
"image": "/images/1002.jpg",
"comment": 3342
},
{
"id": 19,
"title": "奇兵！马修斯绝平补篮＋塔克三分准绝杀 湖人加时险胜需谢他们",
"image": "/images/1004.png",
"comment": 3255
},
{
"id": 20,
"title": "科比生前和乔丹最后一次对话内容曝光，两人互发短信＋科教练发狠",
"image": "/images/1005.jpg",
"comment": 189
},
{
"id": 21,
"title": "英超-曼联轮换10人1-2莱斯特，青木球王破门，曼城提前3轮夺冠",
"image": "/images/1000.png",
"comment": 55
},
{
"id": 22,
"title": "湖人加时复仇尼克斯！浓眉20分塔克三分准绝杀 罗斯空砍27＋6＋6",
"image": "/images/1001.png",
"comment": 1159
},
{
"id": 23,
"title": "荷兰巨大损失！范戴克亲口宣布不参加欧洲杯！重伤缺战已7个月",
"image": "/images/1002.jpg",
"comment": 3342
},
{
"id": 24,
"title": "奇兵！马修斯绝平补篮＋塔克三分准绝杀 湖人加时险胜需谢他们",
"image": "/images/1004.png",
"comment": 3255
},
{
"id": 25,
"title": "科比生前和乔丹最后一次对话内容曝光，两人互发短信＋科教练发狠",
"image": "/images/1005.jpg",
"comment": 189
},
{
"id": 26,
"title": "英超-曼联轮换10人1-2莱斯特，青木球王破门，曼城提前3轮夺冠",
"image": "/images/1000.png",
"comment": 55
},
{
"id": 27,
"title": "湖人加时复仇尼克斯！浓眉20分塔克三分准绝杀 罗斯空砍27＋6＋6",
"image": "/images/1001.png",
"comment": 1159
},
{
"id": 28,
"title": "荷兰巨大损失！范戴克亲口宣布不参加欧洲杯！重伤缺战已7个月",
"image": "/images/1002.jpg",
"comment": 3342
},
{
"id": 29,
"title": "奇兵！马修斯绝平补篮＋塔克三分准绝杀 湖人加时险胜需谢他们",
"image": "/images/1004.png",
"comment": 3255
},
{
"id": 30,
"title": "科比生前和乔丹最后一次对话内容曝光，两人互发短信＋科教练发狠",
"image": "/images/1005.jpg",
"comment": 189
},
{
"id": 31,
"title": "英超-曼联轮换10人1-2莱斯特，青木球王破门，曼城提前3轮夺冠",
"image": "/images/1000.png",
"comment": 55
},
{
"id": 32,
"title": "湖人加时复仇尼克斯！浓眉20分塔克三分准绝杀 罗斯空砍27＋6＋6",
"image": "/images/1001.png",
"comment": 1159
},
{
"id": 33,
"title": "荷兰巨大损失！范戴克亲口宣布不参加欧洲杯！重伤缺战已7个月",
"image": "/images/1002.jpg",
"comment": 3342
},
{
"id": 34,
"title": "奇兵！马修斯绝平补篮＋塔克三分准绝杀 湖人加时险胜需谢他们",
"image": "/images/1004.png",
"comment": 3255
},
{
"id": 35,
"title": "科比生前和乔丹最后一次对话内容曝光，两人互发短信＋科教练发狠",
"image": "/images/1005.jpg",
"comment": 189
}
]
CSS样式：
*{
padding: 0;
margin: 0;
}
body {
font: 14px "Lucida Grande", Helvetica, Arial, sans-serif;
}
a {
color: #00B7FF;
}
#header {
height: 40px;
width: 100%;
background-color: rgb(83,123,255);
line-height: 40px;
margin-right: 20px;
position: fixed;
z-index: 9999;
}
h2{
margin-left: 10px;
color: rgb(230,255,255);
}
#content {
display: flex;
justify-content: space-between;
padding: 10px;
border-bottom: 1px solid #eee;
}
.box {
width: 60%;
height: 80px;
}
.imageBox{
width: 40%;
height: 80px;
margin-left: 20px;
}
.imageBox img {
width: 100%;
height: 100%;
border-radius: 10px;
}
.comment {
margin-top: 5px;
color: #333;
font-size: 12px;
}
#pos {
position: relative;
top: 40px;
}
项目目录结构：
网友评论