{ "openapi": "3.0.1", "info": { "title": "蜻蜓_JOB 第三方 API 接口平台", "description": "纯 AI 能力服务接口，不存储用户业务数据。提供简历优化、面试辅助、规划报告、文书生成等核心能力。", "version": "1.0.0", "contact": { "name": "蜻蜓大学生就业网", "email": "support@qingtingjob.com" } }, "servers": [ { "url": "http://localhost:5001", "description": "开发环境" }, { "url": "https://api.qingtingjob.com", "description": "生产环境" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth2 Client Credentials Flow 获取的 JWT Token" } }, "schemas": { "APIResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "请求是否成功" }, "request_id": { "type": "string", "description": "请求唯一标识" }, "timestamp": { "type": "integer", "description": "响应时间戳（秒）" }, "data": { "type": "object", "description": "业务数据" }, "meta": { "type": "object", "properties": { "processing_time_ms": { "type": "integer", "description": "处理耗时（毫秒）" }, "model": { "type": "string", "description": "使用的AI模型" } } } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [false] }, "request_id": { "type": "string" }, "timestamp": { "type": "integer" }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "错误码" }, "message": { "type": "string", "description": "错误消息" }, "details": { "type": "object", "description": "错误详情" } } } } }, "PersonalInfo": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "description": "姓名", "example": "张三" }, "gender": { "type": "string", "enum": ["男", "女"], "description": "性别" }, "phone": { "type": "string", "description": "手机号", "example": "13800138000" }, "email": { "type": "string", "description": "邮箱", "example": "zhangsan@example.com" } } }, "Education": { "type": "object", "properties": { "school": { "type": "string", "description": "学校名称", "example": "北京大学" }, "major": { "type": "string", "description": "专业名称", "example": "计算机科学与技术" }, "degree": { "type": "string", "enum": ["本科", "硕士", "博士"], "description": "学历" }, "graduation_date": { "type": "string", "format": "date", "description": "毕业时间" } } }, "TargetPosition": { "type": "object", "required": ["position"], "properties": { "position": { "type": "string", "description": "职位名称", "example": "软件工程师" }, "industry": { "type": "string", "description": "行业", "example": "互联网" }, "company_type": { "type": "string", "description": "企业类型", "example": "民营企业" } } }, "StudentInfo": { "type": "object", "required": ["name", "school", "major"], "properties": { "name": { "type": "string", "description": "学生姓名" }, "school": { "type": "string", "description": "学校名称" }, "major": { "type": "string", "description": "专业名称" }, "grade": { "type": "string", "description": "年级" }, "gpa": { "type": "string", "description": "GPA" }, "degree": { "type": "string", "description": "学历" } } } } }, "paths": { "/oauth/token": { "post": { "tags": ["OAuth2 认证"], "summary": "获取访问令牌", "description": "使用 Client Credentials Flow 模式获取 JWT 访问令牌", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": ["grant_type", "client_id", "client_secret"], "properties": { "grant_type": { "type": "string", "enum": ["client_credentials"], "description": "授权类型，固定值" }, "client_id": { "type": "string", "description": "客户端ID", "example": "client_demo_123456789" }, "client_secret": { "type": "string", "description": "客户端密钥", "example": "demo_secret_abc123xyz" }, "scope": { "type": "string", "description": "权限范围，多个用空格分隔", "example": "ai.resume ai.interview" } } } } } }, "responses": { "200": { "description": "成功获取令牌", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "访问令牌" }, "token_type": { "type": "string", "enum": ["Bearer"] }, "expires_in": { "type": "integer", "description": "过期时间（秒）", "example": 7200 }, "scope": { "type": "string", "description": "授权范围" } } } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "客户端认证失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/oauth/token/validate": { "post": { "tags": ["OAuth2 认证"], "summary": "验证访问令牌", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["token"], "properties": { "token": { "type": "string", "description": "访问令牌" } } } } } }, "responses": { "200": { "description": "令牌有效", "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" }, "client_id": { "type": "string" }, "scope": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } } } } } } }, "/oauth/client/register": { "post": { "tags": ["OAuth2 认证"], "summary": "注册新的OAuth客户端", "description": "仅限管理员使用", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["client_name"], "properties": { "client_name": { "type": "string", "description": "客户端名称", "example": "测试客户端" }, "scopes": { "type": "array", "items": { "type": "string", "enum": ["ai.resume", "ai.interview", "ai.report", "ai.wenshu"] }, "description": "权限范围" }, "rate_limit": { "type": "integer", "description": "每小时请求上限", "default": 100 } } } } } }, "responses": { "200": { "description": "注册成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "client_name": { "type": "string" }, "scopes": { "type": "string" }, "rate_limit": { "type": "integer" } } } } } } } } } } }, "/api/v1/ai/resume/generate": { "post": { "tags": ["AI 简历服务"], "summary": "AI简历生成", "description": "根据个人信息和求职意向生成简历内容", "security": [ { "BearerAuth": ["ai.resume"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "请求唯一标识（UUID v4）" }, "data": { "type": "object", "required": ["personal_info", "target_position"], "properties": { "personal_info": { "$ref": "#/components/schemas/PersonalInfo" }, "education": { "$ref": "#/components/schemas/Education" }, "target_position": { "$ref": "#/components/schemas/TargetPosition" }, "additional_info": { "type": "object", "properties": { "internships": { "type": "array", "description": "实习经历" }, "projects": { "type": "array", "description": "项目经历" } } } } } } }, "example": { "request_id": "req_550e8400-e29b-41d4-a716-446655440000", "data": { "personal_info": { "name": "张三", "gender": "男", "phone": "13800138000", "email": "zhangsan@example.com" }, "education": { "school": "北京大学", "major": "计算机科学与技术", "degree": "本科", "graduation_date": "2025-06" }, "target_position": { "position": "软件工程师", "industry": "互联网", "company_type": "民营企业" } } } } } }, "responses": { "200": { "description": "生成成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/APIResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "resume": { "type": "object", "properties": { "summary": { "type": "string", "description": "个人简介" }, "education_detail": { "type": "string", "description": "教育背景详细描述" }, "work_experience": { "type": "array", "description": "工作经历" }, "projects": { "type": "array", "description": "项目经历" }, "skills": { "type": "array", "description": "技能特长" } } } } } } } ] } } } }, "400": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "未授权", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "权限不足", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/ai/resume/diagnose": { "post": { "tags": ["AI 简历服务"], "summary": "AI简历诊断", "description": "对简历内容进行多维度诊断分析", "security": [ { "BearerAuth": ["ai.resume"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": ["resume_text"], "properties": { "resume_text": { "type": "string", "description": "简历文本内容" } } } } } } } }, "responses": { "200": { "description": "诊断成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/APIResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "diagnosis": { "type": "object", "properties": { "score": { "type": "integer", "description": "总分（0-100）" }, "strengths": { "type": "array", "items": { "type": "string" }, "description": "优点" }, "weaknesses": { "type": "array", "items": { "type": "string" }, "description": "不足" }, "suggestions": { "type": "array", "items": { "type": "string" }, "description": "改进建议" } } } } } } } ] } } } } } } }, "/api/v1/ai/resume/autofill": { "post": { "tags": ["AI 简历服务"], "summary": "AI简历智能填充", "description": "根据职位描述智能生成简历填充建议", "security": [ { "BearerAuth": ["ai.resume"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": ["job_description"], "properties": { "job_description": { "type": "string", "description": "职位描述" }, "user_info": { "type": "object", "description": "用户基本信息（可选）" } } } } } } } }, "responses": { "200": { "description": "生成成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/APIResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "autofill_suggestions": { "type": "object", "properties": { "key_skills": { "type": "array", "items": { "type": "string" } }, "suggested_keywords": { "type": "array", "items": { "type": "string" } }, "resume_summary": { "type": "string" }, "optimization_tips": { "type": "array", "items": { "type": "string" } } } } } } } } ] } } } } } } }, "/api/v1/ai/interview/question": { "post": { "tags": ["AI 面试服务"], "summary": "生成面试题目", "description": "根据岗位类型生成面试题目", "security": [ { "BearerAuth": ["ai.interview"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": ["position_type"], "properties": { "position_type": { "type": "string", "description": "岗位类型", "example": "技术岗位" }, "difficulty": { "type": "string", "enum": ["简单", "中等", "困难"], "default": "中等", "description": "难度" }, "count": { "type": "integer", "default": 5, "description": "题目数量" } } } } } } } }, "responses": { "200": { "description": "生成成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/APIResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "category": { "type": "string" }, "question": { "type": "string" }, "difficulty": { "type": "string" } } } } } } } } ] } } } } } } }, "/api/v1/ai/interview/evaluate": { "post": { "tags": ["AI 面试服务"], "summary": "评价面试回答", "description": "对面试回答进行多维度评价", "security": [ { "BearerAuth": ["ai.interview"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": ["question", "answer"], "properties": { "question": { "type": "string", "description": "面试问题" }, "answer": { "type": "string", "description": "面试回答" }, "position_type": { "type": "string", "description": "岗位类型" } } } } } } } }, "responses": { "200": { "description": "评价成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/APIResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "evaluation": { "type": "object", "properties": { "score": { "type": "integer" }, "dimensions": { "type": "object" }, "strengths": { "type": "array", "items": { "type": "string" } }, "weaknesses": { "type": "array", "items": { "type": "string" } }, "suggestions": { "type": "array", "items": { "type": "string" } } } } } } } } ] } } } } } } }, "/api/v1/ai/interview/summary": { "post": { "tags": ["AI 面试服务"], "summary": "生成面试总结", "description": "根据面试记录生成总结报告", "security": [ { "BearerAuth": ["ai.interview"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": ["qa_pairs"], "properties": { "qa_pairs": { "type": "array", "description": "面试问答对", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } } }, "position_type": { "type": "string", "description": "岗位类型" } } } } } } } }, "responses": { "200": { "description": "生成成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/APIResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "overall_score": { "type": "integer" }, "strengths": { "type": "array", "items": { "type": "string" } }, "weaknesses": { "type": "array", "items": { "type": "string" } }, "hiring_recommendation": { "type": "string", "enum": ["推荐", "待定", "不推荐"] }, "summary": { "type": "string" } } } } } } } ] } } } } } } }, "/api/v1/ai/report/generate": { "post": { "tags": ["AI 报告服务"], "summary": "通用报告生成", "description": "根据报告类型生成规划报告", "security": [ { "BearerAuth": ["ai.report"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": ["report_type", "student_info"], "properties": { "report_type": { "type": "string", "enum": ["plan", "civil", "kaoyan", "soe"], "description": "报告类型" }, "student_info": { "$ref": "#/components/schemas/StudentInfo" }, "target_info": { "type": "object", "description": "目标信息" }, "output_format": { "type": "string", "enum": ["markdown", "html", "json"], "default": "markdown" } } } } } } } }, "responses": { "200": { "description": "生成成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/APIResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "report": { "type": "object", "properties": { "report_type": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "output_format": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" } } } } } } } ] } } } } } } }, "/api/v1/ai/report/plan": { "post": { "tags": ["AI 报告服务"], "summary": "大学陪跑规划报告", "description": "生成大学陪跑规划报告", "security": [ { "BearerAuth": ["ai.report"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": ["student_info"], "properties": { "student_info": { "$ref": "#/components/schemas/StudentInfo" }, "target_info": { "type": "object", "properties": { "schools": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "responses": { "200": { "description": "生成成功" } } } }, "/api/v1/ai/report/civil": { "post": { "tags": ["AI 报告服务"], "summary": "考公报考分析报告", "description": "生成公务员报考分析报告", "security": [ { "BearerAuth": ["ai.report"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": ["student_info"], "properties": { "student_info": { "type": "object", "properties": { "name": { "type": "string" }, "major": { "type": "string" }, "degree": { "type": "string" } } }, "target_info": { "type": "object", "properties": { "positions": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "responses": { "200": { "description": "生成成功" } } } }, "/api/v1/ai/report/kaoyan": { "post": { "tags": ["AI 报告服务"], "summary": "考研规划报告", "description": "生成考研规划报告", "security": [ { "BearerAuth": ["ai.report"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": ["student_info"], "properties": { "student_info": { "type": "object", "properties": { "name": { "type": "string" }, "school": { "type": "string" }, "major": { "type": "string" }, "score": { "type": "object", "properties": { "english": { "type": "string" }, "math": { "type": "string" }, "politics": { "type": "string" }, "major": { "type": "string" } } } } }, "target_info": { "type": "object", "properties": { "schools": { "type": "array", "items": { "type": "string" } }, "majors": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "responses": { "200": { "description": "生成成功" } } } }, "/api/v1/ai/report/soe": { "post": { "tags": ["AI 报告服务"], "summary": "央国企求职报告", "description": "生成央国企求职报告", "security": [ { "BearerAuth": ["ai.report"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": ["student_info"], "properties": { "student_info": { "type": "object", "properties": { "name": { "type": "string" }, "school": { "type": "string" }, "major": { "type": "string" }, "degree": { "type": "string" } } }, "target_info": { "type": "object", "properties": { "enterprises": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "responses": { "200": { "description": "生成成功" } } } }, "/api/v1/ai/wenshu/generate": { "post": { "tags": ["AI 文书服务"], "summary": "通用文书生成", "description": "根据文书类型生成申请文书", "security": [ { "BearerAuth": ["ai.wenshu"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": ["wenshu_type", "applicant_info"], "properties": { "wenshu_type": { "type": "string", "enum": ["personal_statement", "recommendation_letter", "cover_letter"], "description": "文书类型" }, "applicant_info": { "type": "object", "description": "申请者信息" }, "target_info": { "type": "object", "description": "目标信息" }, "language": { "type": "string", "enum": ["zh", "en"], "default": "zh" } } } } } } } }, "responses": { "200": { "description": "生成成功", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/APIResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "wenshu": { "type": "object", "properties": { "wenshu_type": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "language": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" } } } } } } } ] } } } } } } }, "/api/v1/ai/wenshu/personal-statement": { "post": { "tags": ["AI 文书服务"], "summary": "个人陈述生成", "description": "生成留学/考研个人陈述", "security": [ { "BearerAuth": ["ai.wenshu"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": ["applicant_info"], "properties": { "applicant_info": { "type": "object", "properties": { "name": { "type": "string" }, "school": { "type": "string" }, "major": { "type": "string" }, "gpa": { "type": "string" }, "achievements": { "type": "array", "items": { "type": "string" } }, "experiences": { "type": "array", "items": { "type": "string" } } } }, "target_info": { "type": "object", "properties": { "school": { "type": "string" }, "program": { "type": "string" } } }, "language": { "type": "string", "enum": ["zh", "en"], "default": "zh" } } } } } } } }, "responses": { "200": { "description": "生成成功" } } } }, "/api/v1/ai/wenshu/recommendation-letter": { "post": { "tags": ["AI 文书服务"], "summary": "推荐信生成", "description": "生成学术/职业推荐信", "security": [ { "BearerAuth": ["ai.wenshu"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": ["applicant_info"], "properties": { "applicant_info": { "type": "object", "properties": { "recommender_name": { "type": "string" }, "recommender_title": { "type": "string" }, "recommender_institution": { "type": "string" }, "applicant_name": { "type": "string" }, "relationship": { "type": "string" } } }, "target_info": { "type": "object", "properties": { "position": { "type": "string" }, "institution": { "type": "string" } } }, "language": { "type": "string", "enum": ["zh", "en"], "default": "zh" } } } } } } } }, "responses": { "200": { "description": "生成成功" } } } }, "/api/v1/ai/wenshu/cover-letter": { "post": { "tags": ["AI 文书服务"], "summary": "求职信生成", "description": "生成求职信/自荐信", "security": [ { "BearerAuth": ["ai.wenshu"] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "data": { "type": "object", "required": ["applicant_info"], "properties": { "applicant_info": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "school": { "type": "string" }, "major": { "type": "string" }, "skills": { "type": "array", "items": { "type": "string" } } } }, "target_info": { "type": "object", "properties": { "company": { "type": "string" }, "position": { "type": "string" }, "requirements": { "type": "array", "items": { "type": "string" } } } }, "language": { "type": "string", "enum": ["zh", "en"], "default": "zh" } } } } } } } }, "responses": { "200": { "description": "生成成功" } } } }, "/health": { "get": { "tags": ["系统"], "summary": "健康检查", "security": [], "responses": { "200": { "description": "服务健康", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["healthy"] }, "service": { "type": "string" }, "version": { "type": "string" } } } } } } } } } }, "tags": [ { "name": "OAuth2 认证", "description": "OAuth2 Client Credentials Flow 认证接口" }, { "name": "AI 简历服务", "description": "AI简历生成、诊断、智能填充服务" }, { "name": "AI 面试服务", "description": "AI面试题目生成、回答评价、总结服务" }, { "name": "AI 报告服务", "description": "大学陪跑/考公/考研/央国企四类规划报告生成服务" }, { "name": "AI 文书服务", "description": "个人陈述/推荐信/求职信等文书生成服务" }, { "name": "系统", "description": "系统健康检查等接口" } ] }