1.接口文档编写
1.1 什么是接口文档
在项目开发中,web项目的前后端通常分离开发,
此过程中,需要由前后端工程师共同定义接口,编写接口文档,
之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护。
1.2 创建文件
1.3 接口文档示例
(docs/interface/readme.md)
1.3.1 旅游网的接口文档
旅游网的接口文档 RESTful风格接口
* 200请求数据成功
* 201提交数据成功
* 400参数错误
* 401未登录
* 403没有权限
* 404目标资源丢失
* 500服务器正忙
接口强求地址
1.测试环境
2.生产环境
1.3.2 错误代码文字提示
错误代码文字提示
```
{
"error_code":"400000"
"error_msg":"该字段不能为空。"
"error_list":{
"password":["该字段不能为空"]
}
}
```
1.3.3 请求头添加内容/分页响应的参数
html
<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 请求参数
html
### 请求参数
<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 返回结果
python
## 返回结果
```
{
"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
javascript
//用于访问服务器端接口
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
javascript
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)获取到接口里的数据
javascript
<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.objects
console.log(res.data)
})
}
</script>
src\components\home\Banner.vue全部代码:
html
<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://向目标发起请求时,携带数据。
javascript
<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等。
javascript
<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
javascript
<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.objects
console.log(FineList.value)
})
}
onMounted(()=>{
getFineList()
})
</script>
文件地址:src\components\common\ListSight.vue
javascript
<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>