{
    "swagger": "2.0",
    "info": {
        "description": "Third-party integration service, providing CAPTCHA and external provider integrations",
        "title": "Thirdparty Service API",
        "contact": {},
        "version": "1.0.0"
    },
    "basePath": "/api/v1",
    "paths": {
        "/internal/thirdparty/captcha/challenge": {
            "get": {
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "根据指定提供者类型生成CAPTCHA挑战数据，PoW类型返回随机挑战码和难度值，Turnstile类型返回Site Key，用于前端初始化验证组件并开始人机验证流程",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "第三方验证"
                ],
                "summary": "获取CAPTCHA挑战",
                "parameters": [
                    {
                        "enum": [
                            "pow",
                            "turnstile"
                        ],
                        "type": "string",
                        "default": "pow",
                        "description": "验证提供者类型（pow / turnstile）",
                        "name": "provider",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "default": "default",
                        "description": "应用范围标识，用于区分不同业务页面或场景的挑战",
                        "name": "scope",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "PoW挑战难度值，数值越大计算难度越高（仅对pow类型有效）",
                        "name": "difficulty",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "挑战生成成功，返回挑战ID、类型、挑战数据和过期时间",
                        "schema": {
                            "$ref": "#/definitions/dto.DataResponse-captcha_Challenge"
                        }
                    },
                    "400": {
                        "description": "请求参数错误（不支持的验证提供者类型）",
                        "schema": {
                            "$ref": "#/definitions/dto.SimpleResponse"
                        }
                    },
                    "429": {
                        "description": "CAPTCHA挑战请求过于频繁，请稍后重试",
                        "schema": {
                            "$ref": "#/definitions/dto.SimpleResponse"
                        }
                    },
                    "500": {
                        "description": "挑战生成服务不可用",
                        "schema": {
                            "$ref": "#/definitions/dto.SimpleResponse"
                        }
                    }
                }
            }
        },
        "/internal/thirdparty/captcha/verify": {
            "post": {
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "接收用户提交的CAPTCHA令牌（PoW工作量证明计算结果或Turnstile验证Token），调用对应的验证提供者进行服务端校验，返回验证结果（是否通过、评分及错误码）",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "第三方验证"
                ],
                "summary": "验证CAPTCHA令牌",
                "parameters": [
                    {
                        "description": "CAPTCHA验证请求：提供者类型、令牌、挑战ID、操作类型和客户端IP",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/gitee_com_linmes_authms_micro-services_thirdparty-service_internal_dto.CaptchaVerifyRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "验证完成，返回是否通过、评分及错误码",
                        "schema": {
                            "$ref": "#/definitions/dto.DataResponse-gitee_com_linmes_authms_micro-services_thirdparty-service_internal_dto_CaptchaVerifyResponse"
                        }
                    },
                    "400": {
                        "description": "请求参数错误（缺少必填字段或不支持的验证提供者）",
                        "schema": {
                            "$ref": "#/definitions/dto.SimpleResponse"
                        }
                    },
                    "429": {
                        "description": "CAPTCHA验证请求过于频繁，请稍后重试",
                        "schema": {
                            "$ref": "#/definitions/dto.SimpleResponse"
                        }
                    },
                    "500": {
                        "description": "验证服务不可用",
                        "schema": {
                            "$ref": "#/definitions/dto.SimpleResponse"
                        }
                    }
                }
            }
        },
        "/internal/thirdparty/health": {
            "get": {
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "检查所有已注册CAPTCHA提供者（PoW、Turnstile等）的健康状态，依次调用各提供者的健康检查接口，返回每个提供者的运行状态信息",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "第三方验证"
                ],
                "summary": "第三方验证服务健康检查",
                "responses": {
                    "200": {
                        "description": "各提供者健康状态：healthy 表示正常，unhealthy 后附具体错误信息",
                        "schema": {
                            "type": "object",
                            "additionalProperties": {
                                "type": "string"
                            }
                        }
                    },
                    "400": {
                        "description": "请求参数错误",
                        "schema": {
                            "$ref": "#/definitions/dto.SimpleResponse"
                        }
                    },
                    "500": {
                        "description": "服务内部错误",
                        "schema": {
                            "$ref": "#/definitions/dto.SimpleResponse"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "captcha.Challenge": {
            "type": "object",
            "properties": {
                "data": {
                    "$ref": "#/definitions/captcha.ChallengeData"
                },
                "expires_at": {
                    "type": "string"
                },
                "id": {
                    "type": "string"
                },
                "site_key": {
                    "type": "string"
                },
                "type": {
                    "type": "string"
                }
            }
        },
        "captcha.ChallengeData": {
            "type": "object",
            "properties": {
                "challenge": {
                    "type": "string"
                },
                "difficulty": {
                    "type": "integer"
                }
            }
        },
        "dto.DataResponse-captcha_Challenge": {
            "type": "object",
            "properties": {
                "code": {
                    "type": "integer"
                },
                "data": {
                    "$ref": "#/definitions/captcha.Challenge"
                },
                "message": {
                    "type": "string"
                },
                "timestamp": {
                    "type": "string"
                }
            }
        },
        "dto.DataResponse-gitee_com_linmes_authms_micro-services_thirdparty-service_internal_dto_CaptchaVerifyResponse": {
            "type": "object",
            "properties": {
                "code": {
                    "type": "integer"
                },
                "data": {
                    "$ref": "#/definitions/gitee_com_linmes_authms_micro-services_thirdparty-service_internal_dto.CaptchaVerifyResponse"
                },
                "message": {
                    "type": "string"
                },
                "timestamp": {
                    "type": "string"
                }
            }
        },
        "dto.SimpleResponse": {
            "type": "object",
            "properties": {
                "code": {
                    "type": "integer"
                },
                "message": {
                    "type": "string"
                },
                "timestamp": {
                    "type": "string"
                }
            }
        },
        "gitee_com_linmes_authms_micro-services_thirdparty-service_internal_dto.CaptchaVerifyRequest": {
            "type": "object",
            "required": [
                "provider",
                "token"
            ],
            "properties": {
                "action": {
                    "type": "string"
                },
                "challenge_id": {
                    "type": "string"
                },
                "provider": {
                    "type": "string"
                },
                "remote_ip": {
                    "type": "string"
                },
                "token": {
                    "type": "string"
                }
            }
        },
        "gitee_com_linmes_authms_micro-services_thirdparty-service_internal_dto.CaptchaVerifyResponse": {
            "type": "object",
            "properties": {
                "action": {
                    "type": "string"
                },
                "error_codes": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "provider": {
                    "type": "string"
                },
                "score": {
                    "type": "number"
                },
                "success": {
                    "type": "boolean"
                }
            }
        }
    },
    "securityDefinitions": {
        "bearerAuth": {
            "description": "Type \"Bearer\" followed by a space and JWT token.",
            "type": "apiKey",
            "name": "Authorization",
            "in": "header"
        }
    },
    "tags": [
        {
            "description": "第三方验证：CAPTCHA、人机验证",
            "name": "第三方验证"
        }
    ]
}