1.接口文档编写
1.1 什么是接口文档
在项目开发中，web项目的前后端通常分离开发，
此过程中，需要由前后端工程师共同定义接口，编写接口文档，
之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。
1.2 创建文件
1.3 接口文档示例
（docs/interface/readme.md）
1.3.1 旅游网的接口文档
# 旅游网的接口文档 RESTful风格接口
* 200请求数据成功
* 201提交数据成功
* 400参数错误
* 401未登录
* 403没有权限
* 404目标资源丢失
* 500服务器正忙
## 接口强求地址
1.测试环境
http://test.xxx.top
2.生产环境
http://www.xxx.com
1.3.2 错误代码文字提示
## 错误代码文字提示
```
{
"error_code":"400000"
"error_msg":"该字段不能为空。"
"error_list":{
"password":["该字段不能为空"]
}
}
```
1.3.3 请求头添加内容/分页响应的参数
<table class="table table-hover table-condensed"><thead><tr><th>字段</th><th>类型</th><th>说明</th></tr></thead><tbody><tr class="info"><td>meta</td><td></td><td>分页元数据，解释如下</td></tr><tr><td>total_count</td><td>int</td><td>根据传入的条件检索出的记录条数</td></tr><tr><td>current_count</td><td>int</td><td>当前第几页</td></tr><tr><td>page_count</td><td>int</td><td>总页数</td></tr><tr class="info"><td>objec</td><td>Array</td><td>objects为返回的对象列表</td></tr></tbody>
</table>1.3.4 一级/二级标题
## 接口列表
### 1.系统模块### 2.景点模块
1.4 首页轮播图的接口
（trip_server\docs\interface\system\slider_list.md）
1.4.1 请求地址/调用方式
## 首页轮播图的接口
### 请求地址
/system/slider/list
### 调用方式
GET
1.4.2 请求参数
### 请求参数
<table>
<thead>
<tr><th>字段</th><th>必选</th><th>类型</th><th>说明</th>
</tr>
</thead>
<tbody>
<tr><td>types</td><td>true</td><td>int</td><td>轮播图类型(10:首页轮播)</td>
</tr>
</tbody>
</table>1.4.3 返回结果
## 返回结果
```
{"meta":{"total_count":3,"page_count":2,"current_page":1},"objects":[{"pk":1,"name":"轮播图1","desc":null,"img":http://django.xxx.com/medias/slider/banner1.jpg,"target_url":null},{"pk":2,"name":"轮播图2","desc":null,"img":http://django.xxx.com/medias/slider/banner2.jpg,"target_url":null}]
}```2.轮播图接口数据获取
2.1 接口配置
文件位置：src\utils\apis.js
//用于访问服务器端接口
const apiHost = "/api"//系统相关的接口
const SystemApis = {sliderListUrl:apiHost+"/system/slider/list/"
}
//景点相关的接口
const SightApis = {sightListUrl:apiHost+"/sight/sight/list/"
}
//对外暴露
export{SystemApis,SightApis
}2.2 前端跨域
文件地址：vite.config.js
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'export default defineConfig({plugins: [vue(),],resolve: {alias: {'@': fileURLToPath(new URL('./src', import.meta.url))}},//👇server:{proxy:{'/api':{target:'http://localhost:8000',changeOrigin:true,rewrite:(path)=>path.replace(/^\/api/,'')}}}//👈
})
2.3 配置服务端媒体地址
文件位置：pycharm--trip_server/settings.py
3. 上传轮播图动态数据
3.1 配置轮播图数据接口
格式见2.2
3.2 访问接口获取数据
import { ref,onMounted } from 'vue';// 获得vue中提供的响应式工具及生命周期工具
import { ajax } from '@/utils/ajax';//获得axios异步请求对象
import { SystemApis } from '@/utils/apis';//获得访问目标(轮播图)
const bannerList = ref([ ])//创建列表用于存放接口返回的轮播图数据
bannerList.value =res.data.objects//将获取的轮播图数据，给到响应式对象bannerlist中
console.log(res.data) //控制台输出响应对象中的数据，
测试是否console.log(bannerList.value)获取到接口里的数据
<script setup>
import { ref,onMounted } from 'vue';
import { ajax } from '@/utils/ajax';
import { SystemApis } from '@/utils/apis';
//轮播图原静态数据
// const bannerList = ref([
// {id: '1', imgUrl: '/static/home/banner/banner1.jpg'},
// {id: '2', imgUrl: '/static/home/banner/banner2.jpg'},
// {id: '3', imgUrl: '/static/home/banner/banner3.jpg'}
// ])
const bannerList = ref([])
//访问接口获取数据
const getBannerList=()=>{ajax.get(SystemApis.sliderListUrl).then(res =>{bannerList.value =res.data.objectsconsole.log(res.data) })
}
</script>src\components\home\Banner.vue全部代码：
<script setup>
import { ref,onMounted } from 'vue';
import { ajax } from '@/utils/ajax';
import { SystemApis } from '@/utils/apis';const bannerList = ref([])
//访问接口获取数据
const getBannerList=()=>{ajax.get(SystemApis.sliderListUrl).then(res =>{bannerList.value =res.data.objects})
}
onMounted(()=>{getBannerList()
})
</script><template><div class="home-banner-box"><!-- 轮播图 --><van-swipe class="my-swipe" :autoplay="3000" indicator-color="white"><van-swipe-item v-for="item in bannerList" :key="item.id"><img :src="item.img_url"><!-- 注意“img_url”👆命名格式 --></van-swipe-item></van-swipe></div>
</template><style lang="less">
.home-banner-box {img {width: 100%;height: auto;}
}
</style>4.上传热门景点动态数据（by Axios）
4.1 配置轮播图数据接口
略
4.2 <script> 模块：
params://向目标发起请求时，携带数据。
<script setup>
import { ref,onMounted } from 'vue';
import { ajax } from '@/utils/ajax';
import { SightApis } from '@/utils/apis';
//原热门景点静态数据
// const hotList = ref([
// { id: 1, img: '/static/home/hot/h1.jpg', name: '景点名称', price: 65 },
// { id: 2, img: '/static/home/hot/h2.jpg', name: '景点名称', price: 65 },
// {........}
// ])
const hotList = ref([])
const getHotList = () => {ajax.get(SightApis.sightListUrl,{params:{is_hot:1}}).then(({data})=>{hotList.value = data.objects// console.log(hotList.value)})
}
onMounted(()=>{getHotList()
})
</script>4.3 <template>模块：
依照数据库内格式修改动态数据名称，如main_img、min_price等。
<template><!-- 热门景点 --><div class="home-hot-box"><van-cell title="热门推荐" is-link value="全部榜单" icon="/static/home/hot/fire.png" title-style="text-align:left" /><div class="box-main"><RouterLink class="hot-item" v-for="item in hotList" :key="item.id" :to="`#`"><div class="img"><span class="span"></span><img :src="item.main_img" alt=""></div><h5 class="van-ellipsis">{{ item.name }}</h5><div class="line-price"><span class="price">￥{{ item.min_price }}</span>起</div></RouterLink></div></div></template>5.上传精选景点动态数据（by Axios）
文件地址：src\components\home\Fine.vue
<script setup>
import ListSight from '../common/ListSight.vue';
import { ref,onMounted } from 'vue';
import { ajax } from '@/utils/ajax';
import { SightApis } from '@/utils/apis';
//原精选景点静态数据
// const fineList = ref([
// { id: 1, name: '景点名称', score: 5, price: 98 },
// { id: 2, name: '景点名称', score: 4.5, price: 98 },
// {.........},
// ])
const FineList = ref([])
const getFineList= ()=>{ajax.get(SightApis.sightListUrl,{params:{is_top:1}}).then(({data})=>{FineList.value = data.objectsconsole.log(FineList.value)})
}
onMounted(()=>{getFineList()
})
</script>文件地址：src\components\common\ListSight.vue
<template><a href="#" class="sight-item"><img :src="item.main_img" alt=""><div class="right"><h5>{{ item.name }}</h5><van-rate v-model="item.score" allow-half readonly="" /><div class="tips">{{item.comment_count}}人点评|100%满意</div><div class="tips" light>{{item.province}}-{{item.city}}</div><div class="line-price">￥{{ item.min_price }}</div></div></a>
</template>
