问卷系统接口文档

卷王问卷系统提供了完整的 RESTful API 接口，支持问卷创建、管理、数据收集和分析等功能。本文档将指导您如何访问和使用这些接口。

📖 接口文档访问方式

方式一：在线接口文档（推荐）

您可以直接访问我们的在线接口文档，无需部署即可查看完整的 API 规范：

🌐 在线文档地址：https://dev.surveykingpro.cn/swagger-ui/index.html

在线文档具有以下优势：

✅ 实时更新：始终保持最新版本的 API 文档
✅ 交互式测试：可以直接在页面上测试 API 接口
✅ 完整示例：包含详细的请求和响应示例
✅ 即时访问：无需部署，随时查看

方式二：本地开发环境访问

如果您已经部署了卷王问卷系统，可以在本地开发环境中访问 Swagger 文档：

# 启动后端服务后，访问以下地址：
http://localhost:48080/swagger-ui/index.html

# 或者如果您修改了端口，使用相应的端口号：
http://localhost:您的端口号/swagger-ui/index.html

🚀 快速开始

1. API 基础信息

Base URL: http://你的域名/admin-api
数据格式: JSON
认证方式: Bearer Token（JWT）
编码格式: UTF-8

2. 认证说明

大部分 API 接口需要认证，您需要：

获取访问令牌：
```
POST /admin-api/system/auth/login
```
在请求头中添加认证信息：
```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

3. 通用响应格式

所有 API 接口都遵循统一的响应格式：

{
  "code": 200,
  "success": true,
  "message": "操作成功",
  "data": {
    // 具体的响应数据
  }
}

📋 主要接口模块

用户认证模块

用户登录/登出
权限验证
用户信息管理

问卷管理模块

问卷创建/编辑/删除
问卷发布/停止
问卷设置管理

答题模块

问卷答题提交
答题进度管理
答题数据验证

数据统计模块

答题数据统计
图表数据生成
数据导出

系统管理模块

用户管理
角色权限管理
系统配置

🛠️ 开发指南

1. 环境要求

后端: Java 8+, Spring Boot
前端: Node.js 14+, React/Vue
数据库: MySQL 5.7+
缓存: Redis 5.0+

2. SDK 和工具

我们推荐使用以下工具进行 API 开发：

HTTP 客户端工具

Postman: 导入 Swagger JSON 文件进行测试
Insomnia: 轻量级 API 测试工具
curl: 命令行 HTTP 客户端

代码生成工具

Swagger Codegen: 根据 API 文档生成客户端 SDK
OpenAPI Generator: 支持多种编程语言的代码生成

3. 示例代码

JavaScript/Node.js 示例

// 安装依赖：npm install axios

const axios = require('axios');

// 配置 API 基础信息
const apiClient = axios.create({
  baseURL: 'http://your-domain/admin-api',
  headers: {
    'Content-Type': 'application/json',
  }
});

// 登录获取 token
async function login(username, password) {
  try {
    const response = await apiClient.post('/system/auth/login', {
      username,
      password
    });
    
    const token = response.data.data.accessToken;
    // 设置认证头
    apiClient.defaults.headers['Authorization'] = `Bearer ${token}`;
    
    return token;
  } catch (error) {
    console.error('登录失败:', error.response.data);
  }
}

// 获取问卷列表
async function getProjects() {
  try {
    const response = await apiClient.get('/project/page');
    return response.data.data;
  } catch (error) {
    console.error('获取问卷列表失败:', error.response.data);
  }
}

Python 示例

import requests
import json

class SurveyKingAPI:
    def __init__(self, base_url):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({'Content-Type': 'application/json'})
    
    def login(self, username, password):
        """用户登录"""
        url = f"{self.base_url}/system/auth/login"
        data = {
            "username": username,
            "password": password
        }
        
        response = self.session.post(url, json=data)
        if response.status_code == 200:
            result = response.json()
            if result['success']:
                token = result['data']['accessToken']
                self.session.headers['Authorization'] = f'Bearer {token}'
                return token
        
        raise Exception(f"登录失败: {response.text}")
    
    def get_projects(self):
        """获取问卷列表"""
        url = f"{self.base_url}/project/page"
        response = self.session.get(url)
        
        if response.status_code == 200:
            return response.json()['data']
        
        raise Exception(f"获取项目列表失败: {response.text}")

# 使用示例
api = SurveyKingAPI('http://your-domain/admin-api')
token = api.login('your_username', 'your_password')
projects = api.get_projects()

🔧 常见问题

Q1: 如何处理跨域问题？

A: 后端已配置 CORS 支持，如果仍有跨域问题，请检查：

确认请求头设置正确
检查域名和端口配置
考虑使用代理服务器

Q2: 认证 Token 过期怎么办？

A: 当收到 401 状态码时，需要重新登录获取新的 Token：

// 响应拦截器示例
apiClient.interceptors.response.use(
  response => response,
  error => {
    if (error.response?.status === 401) {
      // Token 过期，重新登录
      window.location.href = '/login';
    }
    return Promise.reject(error);
  }
);

Q3: 如何处理大量数据的分页？

A: 使用分页参数进行数据查询：

// 分页请求示例
const getProjectsWithPagination = async (page = 1, size = 10) => {
  const response = await apiClient.get('/project/page', {
    params: {
      pageNo: page,
      pageSize: size
    }
  });
  return response.data;
};

Q4: 如何上传文件？

A: 使用 FormData 进行文件上传：

const uploadFile = async (file) => {
  const formData = new FormData();
  formData.append('file', file);
  
  const response = await apiClient.post('/file/upload', formData, {
    headers: {
      'Content-Type': 'multipart/form-data'
    }
  });
  
  return response.data;
};

📞 技术支持

如果您在使用接口过程中遇到问题，可以：

查看在线文档：https://dev.surveykingpro.cn/swagger-ui/index.html
查看错误码说明：每个响应都包含详细的错误信息
联系技术支持：通过官方渠道获取帮助

📝 更新日志

接口文档会持续更新，建议：

定期查看在线文档获取最新信息
关注版本更新通知
测试新接口前先查阅文档变更

💡 提示：建议优先使用在线接口文档，它提供了最完整和最新的 API 信息，支持在线测试，是开发过程中的最佳参考。

问卷系统接口文档

📖 接口文档访问方式​

方式一：在线接口文档（推荐）​

方式二：本地开发环境访问​

🚀 快速开始​

1. API 基础信息​

2. 认证说明​

3. 通用响应格式​

📋 主要接口模块​

用户认证模块​

问卷管理模块​

答题模块​

数据统计模块​

系统管理模块​

🛠️ 开发指南​

1. 环境要求​

2. SDK 和工具​

HTTP 客户端工具​

代码生成工具​

3. 示例代码​

JavaScript/Node.js 示例​

Python 示例​

🔧 常见问题​

Q1: 如何处理跨域问题？​

Q2: 认证 Token 过期怎么办？​

Q3: 如何处理大量数据的分页？​

Q4: 如何上传文件？​

📞 技术支持​

📝 更新日志​