您说得对,我需要严格基于项目中前后端实际交互的API来设计接口文档。让我仔细分析项目中的代码:
接口(Application Programming Interface,简称API)是不同软件组件之间进行通信的规范和协议。在乡村休闲旅游系统中,首页推荐模块接口负责为移动端应用提供首页展示所需的各类推荐数据。
首页推荐模块接口设计遵循RESTful API设计原则,采用HTTP协议进行数据传输,使用JSON格式进行数据交换。接口设计基于项目实际的前后端代码实现。
| 接口名称 | 向乡村旅游系统获取首页综合推荐数据的接口 |
|---|---|
| 接口描述 | 1.用于首页一次性获取所有推荐模块数据,包括轮播图、热门景点、精选路线、附近推荐等<br/>2.接口地址:GET /home/data<br/>3.支持基于地理位置的个性化推荐,返回JSON格式的综合数据 |
| 字段名称 | 字段来源 | 示例 | 逻辑验证规则 |
|---|---|---|---|
| 请求参数 | |||
| latitude | 用户当前位置GPS信息 | 28.2378 | 1.可选参数,用户当前纬度坐标<br/>2.数据类型:Double,范围-90到90之间<br/>3.用于计算附近推荐内容 |
| longitude | 用户当前位置GPS信息 | 112.9488 | 1.可选参数,用户当前经度坐标<br/>2.数据类型:Double,范围-180到180之间<br/>3.与latitude配合计算距离 |
| 返回参数 | 数据类型 | 示例值 | 字段说明 |
| banners | Array | - | 首页轮播图数据列表 |
| └ id | Integer | 1 | 轮播图唯一标识 |
| └ title | String | "春日花海,邂逅最美乡村" | 轮播图标题,长度不超过30个字符 |
| └ imageUrl | String | "/static/images/banner1.jpg" | 轮播图片URL,建议尺寸750x300像素 |
| └ type | String | "attraction" | 跳转类型:attraction-景点详情,culture-文化体验,farmstay-农家乐 |
| └ targetId | Integer | 1 | 跳转目标ID,用于页面跳转参数 |
| modules | Array | - | 功能模块入口配置,固定返回4个主要功能模块 |
| └ title | String | "乡村景点" | 模块名称,长度不超过10个字符 |
| └ icon | String | "location" | 模块图标标识,对应uni-icons图标名称 |
| └ bgColor | String | "#4CAF50" | 模块背景色,16进制颜色值 |
| └ url | String | "/pages/attraction/list" | 模块跳转路径 |
| hotAttractions | Array | - | 热门景点推荐列表,通过attractionMapper.selectPopularAttractions(6)获取 |
| └ id | Integer | 4 | 景点唯一标识 |
| └ name | String | "青山绿水生态园" | 景点名称,长度不超过30个字符 |
| └ category | String | "自然风光" | 景点分类名称 |
| └ imageUrl | String | "/static/images/attraction4.jpg" | 景点封面图片URL,建议尺寸400x300像素 |
| └ rating | Float | 4.7 | 景点评分,范围1.0-5.0,保留1位小数 |
| └ tags | Array | ["自然", "徒步"] | 景点特色标签,最多5个 |
| featuredRoutes | Array | - | 精选路线推荐列表,通过routeMapper.selectPopularRoutes(3)获取 |
| └ id | Integer | 1 | 路线唯一标识 |
| └ name | String | "乡村一日游" | 路线名称,长度不超过40个字符 |
| └ description | String | "体验最地道的乡村风情,品尝农家美食" | 路线简介,长度不超过100个字符 |
| └ imageUrl | String | "/static/images/route1.jpg" | 路线封面图片URL,建议尺寸600x400像素 |
| └ duration | String | "1天" | 路线游玩时长 |
| └ distance | String | "15公里" | 路线总距离 |
| └ price | String | "¥198/人" | 路线参考价格 |
| nearbyAttractions | Array | - | 附近景点推荐列表,通过attractionMapper.selectNearbyAttractions获取,仅当提供位置信息时返回 |
| └ id | Integer | 1 | 景点唯一标识 |
| └ name | String | "阳光农场" | 景点名称,长度不超过30个字符 |
| └ category | String | "农业体验" | 景点分类名称 |
| └ imageUrl | String | "/static/images/attraction1.jpg" | 景点封面图片URL,建议尺寸400x300像素 |
| └ rating | Float | 4.5 | 景点评分,范围1.0-5.0,保留1位小数 |
| └ latitude | Float | 28.2478 | 景点纬度坐标,保留4位小数 |
| └ longitude | Float | 112.9588 | 景点经度坐标,保留4位小数 |
| └ tags | Array | ["亲子", "采摘"] | 景点特色标签,最多5个 |
| 接口名称 | 向乡村旅游系统获取首页轮播图数据的接口 |
|---|---|
| 接口描述 | 1.专门获取首页轮播图展示内容,支持轮播图管理和统计<br/>2.接口地址:GET /home/banners<br/>3.返回当前有效的轮播图列表,按权重排序 |
| 字段名称 | 字段来源 | 示例 | 逻辑验证规则 |
|---|---|---|---|
| 请求参数 | |||
| 无 | - | - | 该接口不需要请求参数 |
| 返回参数 | 数据类型 | 示例值 | 字段说明 |
| banners | Array | - | 轮播图数据列表,通过HomeService.getBanners()方法返回 |
| └ id | Integer | 1 | 轮播图唯一标识 |
| └ title | String | "春日花海,邂逅最美乡村" | 轮播图主标题,长度不超过30个字符 |
| └ imageUrl | String | "/static/images/banner1.jpg" | 轮播图片URL,建议尺寸750x300像素 |
| └ type | String | "attraction" | 跳转类型:attraction-景点详情,culture-文化体验,farmstay-农家乐 |
| └ targetId | Integer | 1 | 跳转目标ID,用于页面跳转参数 |
| 接口名称 | 向乡村旅游系统获取首页功能模块配置的接口 |
|---|---|
| 接口描述 | 1.获取首页功能模块入口的配置信息,包括图标、颜色、跳转链接等<br/>2.接口地址:GET /home/modules<br/>3.返回功能模块的完整配置数据,支持动态配置 |
| 字段名称 | 字段来源 | 示例 | 逻辑验证规则 |
|---|---|---|---|
| 请求参数 | |||
| 无 | - | - | 该接口不需要请求参数 |
| 返回参数 | 数据类型 | 示例值 | 字段说明 |
| modules | Array | - | 功能模块配置列表,通过HomeService.getModules()方法返回 |
| └ title | String | "乡村景点" | 模块名称,长度不超过10个字符 |
| └ icon | String | "location" | 模块图标标识,对应uni-icons图标名称 |
| └ bgColor | String | "#4CAF50" | 模块背景色,16进制颜色值 |
| └ url | String | "/pages/attraction/list" | 模块跳转路径 |
这个接口设计严格基于项目中HomeController.java、HomeService.java和前端homeApi.js中实际存在的API交互,确保了文档与代码实现的一致性。
您说得对,我应该更严格地基于项目中实际的API交互来设计接口文档。让我重新检查代码并提供更准确的接口设计:
接口(Application Programming Interface,简称API)是不同软件组件之间进行通信的规范和协议。在乡村休闲旅游系统中,首页推荐模块接口负责为移动端应用提供首页展示所需的各类推荐数据。
首页推荐模块接口设计遵循RESTful API设计原则,采用HTTP协议进行数据传输,使用JSON格式进行数据交换。接口设计基于项目实际的前后端代码实现。
| 接口名称 | 向乡村旅游系统获取首页综合推荐数据的接口 |
|---|---|
| 接口描述 | 1.用于首页一次性获取所有推荐模块数据<br/>2.接口地址:GET /home/data<br/>3.支持基于地理位置的个性化推荐 |
| 字段名称 | 字段来源 | 示例 | 逻辑验证规则 |
|---|---|---|---|
| 请求参数 | |||
| latitude | 用户当前位置GPS信息 | 28.2378 | 1.可选参数,用户当前纬度坐标<br/>2.数据类型:Double |
| longitude | 用户当前位置GPS信息 | 112.9488 | 1.可选参数,用户当前经度坐标<br/>2.数据类型:Double |
| 返回参数 | 数据类型 | 示例值 | 字段说明 |
| banners | Array | - | 首页轮播图数据列表 |
| └ id | Integer | 1 | 轮播图唯一标识 |
| └ title | String | "春日花海,邂逅最美乡村" | 轮播图标题 |
| └ imageUrl | String | "/static/images/banner1.jpg" | 轮播图片URL |
| └ type | String | "attraction" | 跳转类型 |
| └ targetId | Integer | 1 | 跳转目标ID |
| modules | Array | - | 功能模块入口配置 |
| └ title | String | "乡村景点" | 模块名称 |
| └ icon | String | "location" | 模块图标标识 |
| └ bgColor | String | "#4CAF50" | 模块背景色 |
| └ url | String | "/pages/attraction/list" | 模块跳转路径 |
| hotAttractions | Array | - | 热门景点推荐列表 |
| └ id | Integer | 4 | 景点唯一标识 |
| └ name | String | "青山绿水生态园" | 景点名称 |
| └ category | String | "自然风光" | 景点分类名称 |
| └ imageUrl | String | "/static/images/attraction4.jpg" | 景点封面图片URL |
| └ rating | Float | 4.7 | 景点评分 |
| └ tags | Array | ["自然", "徒步"] | 景点特色标签 |
| featuredRoutes | Array | - | 精选路线推荐列表 |
| └ id | Integer | 1 | 路线唯一标识 |
| └ name | String | "乡村一日游" | 路线名称 |
| └ description | String | "体验最地道的乡村风情" | 路线简介 |
| └ imageUrl | String | "/static/images/route1.jpg" | 路线封面图片URL |
| └ duration | String | "1天" | 路线游玩时长 |
| └ distance | String | "15公里" | 路线总距离 |
| └ price | String | "¥198/人" | 路线参考价格 |
| nearbyAttractions | Array | - | 附近景点推荐列表(仅当提供位置信息时返回) |
| └ id | Integer | 1 | 景点唯一标识 |
| └ name | String | "阳光农场" | 景点名称 |
| └ category | String | "农业体验" | 景点分类名称 |
| └ imageUrl | String | "/static/images/attraction1.jpg" | 景点封面图片URL |
| └ rating | Float | 4.5 | 景点评分 |
| └ latitude | Float | 28.2478 | 景点纬度坐标 |
| └ longitude | Float | 112.9588 | 景点经度坐标 |
| └ tags | Array | ["亲子", "采摘"] | 景点特色标签 |
| └ distanceText | String | "1.2km" | 距离文字描述 |
| 接口名称 | 向乡村旅游系统获取首页轮播图数据的接口 |
|---|---|
| 接口描述 | 1.专门获取首页轮播图展示内容<br/>2.接口地址:GET /home/banners |
| 字段名称 | 字段来源 | 示例 | 逻辑验证规则 |
|---|---|---|---|
| 请求参数 | |||
| 无 | - | - | 该接口不需要请求参数 |
| 返回参数 | 数据类型 | 示例值 | 字段说明 |
| banners | Array | - | 轮播图数据列表 |
| └ id | Integer | 1 | 轮播图唯一标识 |
| └ title | String | "春日花海,邂逅最美乡村" | 轮播图主标题 |
| └ imageUrl | String | "/static/images/banner1.jpg" | 轮播图片URL |
| └ type | String | "attraction" | 跳转类型 |
| └ targetId | Integer | 1 | 跳转目标ID |
| 接口名称 | 向乡村旅游系统获取首页功能模块配置的接口 |
|---|---|
| 接口描述 | 1.获取首页功能模块入口的配置信息<br/>2.接口地址:GET /home/modules |
| 字段名称 | 字段来源 | 示例 | 逻辑验证规则 |
|---|---|---|---|
| 请求参数 | |||
| 无 | - | - | 该接口不需要请求参数 |
| 返回参数 | 数据类型 | 示例值 | 字段说明 |
| modules | Array | - | 功能模块配置列表 |
| └ title | String | "乡村景点" | 模块名称 |
| └ icon | String | "location" | 模块图标标识 |
| └ bgColor | String | "#4CAF50" | 模块背景色 |
| └ url | String | "/pages/attraction/list" | 模块跳转路径 |
这个接口设计现在严格基于项目中实际的API交互,只包含了前端代码(home/index.vue)中实际使用的字段和后端代码(HomeController.java和HomeService.java)中实际返回的数据。