{
  "openapi": "3.1.0",
  "info": {
    "title": "YLF_Galaxy Public API",
    "version": "1.0.0",
    "description": "YLF_Galaxy 网站目录与当前用户公开接口。"
  },
  "servers": [{ "url": "https://account.ylfcat.top/api/v1" }],
  "paths": {
    "/sites": {
      "get": {
        "summary": "获取已启用网站目录",
        "operationId": "listSites",
        "responses": {
          "200": {
            "description": "按置顶量稳定排序的网站卡片",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/SitePage" } }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/sites/{slug}/redirect": {
      "get": {
        "summary": "跳转到当前配置的外部网站",
        "operationId": "redirectSite",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }
          }
        ],
        "responses": {
          "302": {
            "description": "跳转到管理员当前配置的 HTTPS URL",
            "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/me": {
      "get": {
        "summary": "获取 Access Token 对应的当前用户",
        "operationId": "getCurrentUser",
        "security": [{ "oidc": ["openid"] }],
        "responses": {
          "200": {
            "description": "受 scope 限制的用户资料",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/CurrentUser" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oidc": {
        "type": "openIdConnect",
        "openIdConnectUrl": "https://account.ylfcat.top/.well-known/openid-configuration"
      }
    },
    "schemas": {
      "Site": {
        "type": "object",
        "required": ["id", "slug", "title", "displayUrl", "description", "kind", "pinWeight"],
        "properties": {
          "id": { "type": "string" },
          "slug": { "type": "string" },
          "title": { "type": "string" },
          "displayUrl": { "type": "string" },
          "description": { "type": "string" },
          "kind": { "type": "string", "enum": ["internal", "external"] },
          "pinWeight": { "type": "integer", "minimum": 0, "maximum": 999 },
          "targetUrl": { "type": "string", "format": "uri" }
        }
      },
      "SitePage": {
        "type": "object",
        "required": ["items"],
        "properties": {
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } },
          "total": { "type": "integer" },
          "page": { "type": "integer" },
          "pageSize": { "type": "integer" }
        }
      },
      "CurrentUser": {
        "type": "object",
        "required": ["sub"],
        "properties": {
          "sub": { "type": "string", "description": "稳定用户标识" },
          "preferred_username": { "type": "string" },
          "name": { "type": "string" },
          "picture": { "type": "string", "format": "uri" },
          "email": { "type": "string", "format": "email" },
          "email_verified": { "type": "boolean" }
        }
      },
      "ApiError": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "requestId": { "type": "string" },
              "details": {}
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "未认证",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }
      },
      "Forbidden": {
        "description": "权限或 scope 不足",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }
      },
      "NotFound": {
        "description": "资源不存在",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }
      },
      "RateLimited": {
        "description": "请求过于频繁",
        "headers": { "Retry-After": { "schema": { "type": "integer" } } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }
      }
    }
  }
}