From b778ebc1d87a3877b58b683224b7ab52b1b5747e Mon Sep 17 00:00:00 2001 From: CPTProgrammer <46586216+CPTProgrammer@users.noreply.github.com> Date: Mon, 13 Jul 2026 16:08:43 +0800 Subject: [PATCH] Update CurseForge API documentation --- docs/curseforge/all-schemas.md | 534 +++++++++++++++++++++++++++++++++ docs/curseforge/get-mod.md | 329 ++++++++++++++++++++ docs/curseforge/get.md | 121 +++++++- docs/curseforge/index.md | 79 +++++ 4 files changed, 1053 insertions(+), 10 deletions(-) create mode 100644 docs/curseforge/all-schemas.md create mode 100644 docs/curseforge/get-mod.md create mode 100644 docs/curseforge/index.md diff --git a/docs/curseforge/all-schemas.md b/docs/curseforge/all-schemas.md new file mode 100644 index 0000000..edf538a --- /dev/null +++ b/docs/curseforge/all-schemas.md @@ -0,0 +1,534 @@ +## Schema 定义 + +### Pagination + +分页信息。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `index` | int32 | 本次返回的起始索引（从 0 开始） | +| `pageSize` | int32 | 请求的页大小 | +| `resultCount` | int32 | 本次实际返回数量 | +| `totalCount` | int64 | 符合条件的总数量 | + +--- + +### File + +文件对象。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 文件 ID | +| `gameId` | int32 | 所属游戏 ID | +| `modId` | int32 | 所属项目 ID | +| `isAvailable` | boolean | 是否可下载 | +| `displayName` | string | 显示名称 | +| `fileName` | string | 文件名 | +| `releaseType` | FileReleaseType | 发布类型 | +| `fileStatus` | FileStatus | 文件状态 | +| `hashes` | FileHash[] | 文件哈希列表 | +| `fileDate` | string(date-time) | 文件时间戳 | +| `fileLength` | int64 | 文件大小（字节） | +| `downloadCount` | int64 | 下载次数 | +| `fileSizeOnDisk` | int64 \| null | 磁盘占用 | +| `downloadUrl` | string | 下载地址 | +| `gameVersions` | string[] | 关联的游戏版本字符串列表 | +| `sortableGameVersions` | SortableGameVersion[] | 排序用版本信息 | +| `dependencies` | FileDependency[] | 依赖关系列表 | +| `exposeAsAlternative` | boolean \| null | 是否暴露为替代版本 | +| `parentProjectFileId` | int32 \| null | 父项目文件 ID | +| `alternateFileId` | int32 \| null | 替代文件 ID | +| `isServerPack` | boolean \| null | 是否为服务端包 | +| `serverPackFileId` | int32 \| null | 服务端包文件 ID | +| `isEarlyAccessContent` | boolean \| null | 是否为抢先体验内容 | +| `earlyAccessEndDate` | string(date-time) \| null | 抢先体验结束日期 | +| `fileFingerprint` | int64 | 文件指纹 | +| `modules` | FileModule[] | 文件模块列表 | + +--- + +### FileHash + +文件哈希。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `value` | string | 哈希值 | +| `algo` | HashAlgo | 哈希算法（1=Sha1, 2=Md5） | + +### HashAlgo + +| 值 | 含义 | +|----|------| +| 1 | Sha1 | +| 2 | Md5 | + +--- + +### FileDependency + +文件依赖关系。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `modId` | int32 | 依赖的项目 ID | +| `relationType` | FileRelationType | 关系类型 | + +### FileRelationType + +| 值 | 含义 | +|----|------| +| 1 | EmbeddedLibrary（嵌入库） | +| 2 | OptionalDependency（可选依赖） | +| 3 | RequiredDependency（必需依赖） | +| 4 | Tool（工具） | +| 5 | Incompatible（不兼容） | +| 6 | Include（包含） | + +--- + +### FileModule + +文件中的模块。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | string | 模块名 | +| `fingerprint` | int64 | 模块指纹 | + +--- + +### FileIndex + +文件索引信息（用于最新文件列表）。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `gameVersion` | string | 游戏版本 | +| `fileId` | int32 | 文件 ID | +| `filename` | string | 文件名 | +| `releaseType` | FileReleaseType | 发布类型 | +| `gameVersionTypeId` | int32 \| null | 游戏版本类型 ID | +| `modLoader` | ModLoaderType | Mod Loader 类型 | + +--- + +### SortableGameVersion + +用于排序的版本信息。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `gameVersionName` | string | 原始版本名（如 `1.5b`） | +| `gameVersionPadded` | string | 补齐版本号（如 `0000000001.0000000005`），用于排序 | +| `gameVersion` | string | 清洗后的版本号（如 `1.5`） | +| `gameVersionReleaseDate` | string(date-time) | 版本发布日期 | +| `gameVersionTypeId` | int32 \| null | 游戏版本类型 ID | + +--- + +### Mod + +项目对象。`data` 字段中返回的核心类型。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 项目 ID | +| `gameId` | int32 | 所属游戏 ID | +| `name` | string | 项目名称 | +| `slug` | string | URL Slug | +| `links` | ModLinks | 项目相关链接 | +| `summary` | string | 简要说明 | +| `status` | ModStatus | 项目状态 | +| `downloadCount` | int64 | 总下载次数 | +| `isFeatured` | boolean | 是否精选 | +| `primaryCategoryId` | int32 | 主分类 ID | +| `categories` | Category[] | 所属分类列表 | +| `classId` | int32 \| null | 所属 class ID | +| `authors` | ModAuthor[] | 作者列表 | +| `logo` | ModAsset | Logo 资源 | +| `screenshots` | ModAsset[] | 截图列表 | +| `mainFileId` | int32 | 主文件 ID | +| `latestFiles` | File[] | 最新文件列表 | +| `latestFilesIndexes` | FileIndex[] | 最新文件索引 | +| `latestEarlyAccessFilesIndexes` | FileIndex[] | 最新抢先体验文件索引 | +| `dateCreated` | string(date-time) | 创建日期 | +| `dateModified` | string(date-time) | 最后修改日期 | +| `dateReleased` | string(date-time) | 发布日期 | +| `allowModDistribution` | boolean \| null | 是否允许分发 | +| `gamePopularityRank` | int32 | 游戏内排名 | +| `isAvailable` | boolean | 是否可搜索（实验性/已删除/仅有 alpha 文件时为 false） | +| `thumbsUpCount` | int32 | 点赞数 | +| `rating` | number \| null | 评分 | + +--- + +### ModLinks + +项目相关链接。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `websiteUrl` | string | 官网 | +| `wikiUrl` | string | Wiki | +| `issuesUrl` | string | Issue 跟踪 | +| `sourceUrl` | string | 源码仓库 | + +--- + +### ModAuthor + +项目作者。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 作者 ID | +| `name` | string | 作者名 | +| `url` | string | 作者主页 | + +--- + +### ModAsset + +项目资源（Logo / 截图）。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 资源 ID | +| `modId` | int32 | 所属项目 ID | +| `title` | string | 标题 | +| `description` | string | 描述 | +| `thumbnailUrl` | string | 缩略图 URL | +| `url` | string | 原图 URL | + +--- + +### Category + +分类。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 分类 ID | +| `gameId` | int32 | 所属游戏 ID | +| `name` | string | 分类名称 | +| `slug` | string | URL Slug | +| `url` | string | 分类 URL | +| `iconUrl` | string | 分类图标 URL | +| `dateModified` | string(date-time) | 最后修改日期 | +| `isClass` | boolean \| null | 是否为顶层 class | +| `classId` | int32 \| null | 所属 class ID | +| `parentCategoryId` | int32 \| null | 父分类 ID | +| `displayIndex` | int32 \| null | 显示顺序 | + +--- + +### Game + +游戏对象。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 游戏 ID | +| `name` | string | 游戏名 | +| `slug` | string | Slug | +| `dateModified` | string(date-time) | 最后修改日期 | +| `assets` | GameAssets | 游戏资源 | +| `status` | CoreStatus | 游戏状态 | +| `apiStatus` | CoreApiStatus | API 访问状态 | + +### GameAssets + +| 字段 | 类型 | 说明 | +|------|------|------| +| `iconUrl` | string | 图标 URL | +| `tileUrl` | string | 卡片背景 URL | +| `coverUrl` | string | 封面 URL | + +### CoreStatus + +| 值 | 含义 | +|----|------| +| 1 | Draft | +| 2 | Test | +| 3 | PendingReview | +| 4 | Rejected | +| 5 | Approved | +| 6 | Live | + +### CoreApiStatus + +| 值 | 含义 | +|----|------| +| 1 | Private | +| 2 | Public | + +--- + +### GameVersion + +游戏版本（V2 接口使用）。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 版本 ID | +| `slug` | string | Slug | +| `name` | string | 版本名 | + +--- + +### GameVersionType + +游戏版本类型。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 类型 ID | +| `gameId` | int32 | 游戏 ID | +| `name` | string | 类型名 | +| `slug` | string | Slug | +| `isSyncable` | boolean | 是否可同步 | +| `status` | GameVersionTypeStatus | 状态 | + +--- + +### GameVersionsByType / GameVersionsByType2 + +按类型分组的版本（V1/V2）。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `type` | int32 | 版本类型 | +| `versions` | string[] / GameVersion[] | 该类型下的版本列表（V1 为字符串，V2 为 GameVersion 对象） | + +--- + +### FingerprintsMatchesResult + +指纹匹配结果。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `isCacheBuilt` | boolean | 缓存是否就绪 | +| `exactMatches` | FingerprintMatch[] | 精确匹配 | +| `exactFingerprints` | int[] | 精确匹配的指纹列表 | +| `partialMatches` | FingerprintMatch[] | 部分匹配 | +| `partialMatchFingerprints` | object(dict) | 部分匹配指纹（指纹 → 文件 ID 列表） | +| `installedFingerprints` | int[] | 已安装的指纹 | +| `unmatchedFingerprints` | int[] | 未匹配的指纹 | + +--- + +### FingerprintMatch + +单个指纹匹配结果。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 文件 ID | +| `file` | File | 匹配到的文件 | +| `latestFiles` | File[] | 该项目的最新文件列表 | + +--- + +### FingerprintFuzzyMatch + +模糊指纹匹配结果。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 文件 ID | +| `file` | File | 匹配到的文件 | +| `latestFiles` | File[] | 该项目的最新文件列表 | +| `fingerprints` | int[] | 匹配到的指纹列表 | + +--- + +### FolderFingerprint + +按文件夹分组的指纹（用于模糊匹配请求体）。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `foldername` | string | 文件夹名 | +| `fingerprints` | int[] | 该文件夹下的指纹列表 | + +--- + +### MinecraftGameVersion + +Minecraft 游戏版本信息。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | ID | +| `gameVersionId` | int32 | 游戏版本 ID | +| `versionString` | string | 版本字符串 | +| `jarDownloadUrl` | string | JAR 下载地址 | +| `jsonDownloadUrl` | string | JSON 下载地址 | +| `approved` | boolean | 是否已批准 | +| `dateModified` | string(date-time) | 修改日期 | +| `gameVersionTypeId` | int32 | 版本类型 ID | +| `gameVersionStatus` | GameVersionStatus | 版本状态 | +| `gameVersionTypeStatus` | GameVersionTypeStatus | 版本类型状态 | + +--- + +### MinecraftModLoaderIndex + +Minecraft ModLoader 索引项。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | string | ModLoader 名称 | +| `gameVersion` | string | 对应的游戏版本 | +| `latest` | boolean | 是否最新版 | +| `recommended` | boolean | 是否推荐版 | +| `dateModified` | string(date-time) | 修改日期 | +| `type` | ModLoaderType | ModLoader 类型 | + +--- + +### MinecraftModLoaderVersion + +Minecraft ModLoader 版本详情。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | ID | +| `gameVersionId` | int32 | 游戏版本 ID | +| `minecraftGameVersionId` | int32 | MC 游戏版本 ID | +| `forgeVersion` | string | Forge 版本号 | +| `name` | string | 名称 | +| `type` | ModLoaderType | ModLoader 类型 | +| `downloadUrl` | string | 下载地址 | +| `filename` | string | 文件名 | +| `installMethod` | ModLoaderInstallMethod | 安装方式 | +| `latest` | boolean | 是否最新 | +| `recommended` | boolean | 是否推荐 | +| `approved` | boolean | 是否已批准 | +| `dateModified` | string(date-time) | 修改日期 | +| `mavenVersionString` | string | Maven 版本字符串 | +| `versionJson` | string | 版本 JSON | +| `librariesInstallLocation` | string | 库安装位置 | +| `minecraftVersion` | string | MC 版本 | +| `additionalFilesJson` | string | 额外文件 JSON | +| `installProfileJson` | string | 安装 Profile JSON | + +--- + +## 枚举值完整列表 + +### FileReleaseType + +| 值 | 含义 | +|----|------| +| 1 | Release | +| 2 | Beta | +| 3 | Alpha | + +### FileStatus（完整） + +| 值 | 含义 | +|----|------| +| 1 | Processing | +| 2 | ChangesRequired | +| 3 | UnderReview | +| 4 | Approved | +| 5 | Rejected | +| 6 | MalwareDetected | +| 7 | Deleted | +| 8 | Archived | +| 9 | Testing | +| 10 | Released | +| 11 | ReadyForReview | +| 12 | Deprecated | +| 13 | Baking | +| 14 | AwaitingPublishing | +| 15 | FailedPublishing | +| 16 | Cooking | +| 17 | Cooked | +| 18 | UnderManualReview | +| 19 | ScanningForMalware | +| 20 | ProcessingFile | +| 21 | PendingRelease | +| 22 | ReadyForCooking | +| 23 | PostProcessing | + +### ModStatus + +| 值 | 含义 | +|----|------| +| 1 | New | +| 2 | ChangesRequired | +| 3 | UnderSoftReview | +| 4 | Approved | +| 5 | Rejected | +| 6 | ChangesMade | +| 7 | Inactive | +| 8 | Abandoned | +| 9 | Deleted | +| 10 | UnderReview | + +### ModLoaderType + +| 值 | 含义 | +|----|------| +| 0 | Any | +| 1 | Forge | +| 2 | Cauldron | +| 3 | LiteLoader | +| 4 | Fabric | +| 5 | Quilt | +| 6 | NeoForge | + +### ModsSearchSortField（搜索排序字段） + +| 值 | 含义 | +|----|------| +| 1 | Featured | +| 2 | Popularity | +| 3 | LastUpdated | +| 4 | Name | +| 5 | Author | +| 6 | TotalDownloads | +| 7 | Category | +| 8 | GameVersion | +| 9 | EarlyAccess | +| 10 | FeaturedReleased | +| 11 | ReleasedDate | +| 12 | Rating | + +### SortOrder + +| 值 | 含义 | +|----|------| +| asc | 升序 | +| desc | 降序 | + +### GameVersionStatus + +| 值 | 含义 | +|----|------| +| 1 | Approved | +| 2 | Deleted | +| 3 | New | + +### GameVersionTypeStatus + +| 值 | 含义 | +|----|------| +| 1 | Normal | +| 2 | Deleted | + +### ModLoaderInstallMethod + +| 值 | 含义 | +|----|------| +| 1 | ForgeInstaller | +| 2 | ForgeJarInstall | +| 3 | ForgeInstaller_v2 | +| 4 | FabricInstaller | +| 5 | QuiltInstaller | +| 6 | NeoForgeInstaller | diff --git a/docs/curseforge/get-mod.md b/docs/curseforge/get-mod.md new file mode 100644 index 0000000..f0a3785 --- /dev/null +++ b/docs/curseforge/get-mod.md @@ -0,0 +1,329 @@ +# CurseForge Get Mod API + +> 来源：https://docs.curseforge.com/rest-api/ +> +> API 基础地址：`https://api.curseforge.com`，认证方式：Header `x-api-key: ` + +--- + +## Get Mod + +``` +GET https://api.curseforge.com/v1/mods/{modId} +``` + +获取指定项目的详细信息。 + +### 参数 + +| 参数 | 位置 | 类型 | 必填 | 说明 | +|------|------|------|------|------| +| `modId` | path | int32 | 是 | 项目 ID | + +### 成功响应 + +```jsonc +{ + "data": { + "id": 789, // 项目 ID + "gameId": 432, // 游戏 ID + "name": "My Mod", // 项目名称 + "slug": "my-mod", // URL 中的项目标识 + "links": { // 相关链接（见 ModLinks） + "websiteUrl": "https://...", // 官网 + "wikiUrl": "https://...", // Wiki + "issuesUrl": "https://...", // Issue 追踪 + "sourceUrl": "https://..." // 源码仓库 + }, + "summary": "A mod that does stuff.", // 项目简介 + "status": 4, // 项目状态（见 ModStatus） + "downloadCount": 50000, // 下载次数 + "isFeatured": false, // 是否精选项目 + "primaryCategoryId": 1, // 主分类 ID + "categories": [ // 分类列表（见 Category） + { + "id": 1, // 分类 ID + "gameId": 432, // 游戏 ID + "name": "MC Technology", // 分类名称 + "slug": "technology", // 分类标识 + "url": "https://...", // 分类页面 URL + "iconUrl": "https://...", // 分类图标 URL + "dateModified": "2025-01-01T00:00:00Z", + "isClass": false, + "classId": null, + "parentCategoryId": null, + "displayIndex": 0 + } + ], + "classId": null, // 所属 class ID + "authors": [ // 作者列表（见 ModAuthor） + { + "id": 123, // 作者 ID + "name": "AuthorName", // 作者名 + "url": "https://..." // 作者页面 URL + } + ], + "logo": { // Logo 资源（见 ModAsset） + "id": 100, // 资源 ID + "modId": 789, // 所属项目 ID + "title": "Logo Title", // 资源标题 + "description": "Logo description", // 资源描述 + "thumbnailUrl": "https://...", // 缩略图 URL + "url": "https://..." // 原图 URL + }, + "screenshots": [ // 截图列表（见 ModAsset） + { + "id": 101, + "modId": 789, + "title": "Screenshot 1", + "description": "A screenshot", + "thumbnailUrl": "https://...", + "url": "https://..." + } + ], + "mainFileId": 12345, // 主文件 ID + "latestFiles": [ // 最新文件列表（File，详见 get.md） + { + "id": 12345, // 文件 ID + "gameId": 432, // 游戏 ID + "modId": 789, // 项目 ID + "isAvailable": true, // 是否可下载 + "displayName": "My Mod v1.0", // 显示名称 + "fileName": "my-mod-1.0.jar", // 文件名 + "releaseType": 1, // FileReleaseType + "fileStatus": 10, // FileStatus + "hashes": [ + { "value": "abc123...", "algo": 1 } // FileHash + ], + "fileDate": "2025-01-01T00:00:00Z", // 文件时间戳 + "fileLength": 1048576, // 文件大小（字节） + "downloadCount": 5000, // 下载次数 + "fileSizeOnDisk": 1048576, // 磁盘占用 + "downloadUrl": "https://...", // 下载地址 + "gameVersions": ["1.21.5"], // 关联的游戏版本（字符串列表） + "sortableGameVersions": [ + { + "gameVersionName": "1.21.5", + "gameVersionPadded": "0000000001.0000000021.0000000005", + "gameVersion": "1.21.5", + "gameVersionReleaseDate": "2025-04-01T00:00:00Z", + "gameVersionTypeId": 83806 + } + ], + "dependencies": [ + { + "modId": 123, // 依赖的项目 ID + "relationType": 3 // FileRelationType + } + ], + "exposeAsAlternative": false, + "parentProjectFileId": null, + "alternateFileId": null, + "isServerPack": false, + "serverPackFileId": null, + "isEarlyAccessContent": false, + "earlyAccessEndDate": null, + "fileFingerprint": 1234567890, + "modules": [ + { "name": "main", "fingerprint": 1234567890 } + ] + } + ], + "latestFilesIndexes": [ // 最新文件索引（见 FileIndex） + { + "gameVersion": "1.21.5", // 游戏版本 + "fileId": 12345, // 文件 ID + "filename": "my-mod-1.0.jar", // 文件名 + "releaseType": 1, // FileReleaseType + "gameVersionTypeId": 83806, // 版本类型 ID + "modLoader": 1 // ModLoaderType + } + ], + "latestEarlyAccessFilesIndexes": [], // 最新抢先体验文件索引（见 FileIndex） + "dateCreated": "2024-01-01T00:00:00Z", // 创建时间 + "dateModified": "2025-06-01T00:00:00Z", // 最后修改时间 + "dateReleased": "2024-02-01T00:00:00Z", // 发布时间 + "allowModDistribution": true, // 是否允许分发 + "gamePopularityRank": 42, // 游戏内热门排名 + "isAvailable": true, // 是否可被搜索到 + "thumbsUpCount": 1234, // 点赞数 + "rating": 4.5 // 评分 + } +} +``` + +### 响应字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 项目 ID | +| `gameId` | int32 | 游戏 ID | +| `name` | string | 项目名称 | +| `slug` | string | URL 中的项目标识 | +| `links` | ModLinks | 相关链接（官网、Wiki、Issue、源码） | +| `summary` | string | 项目简介 | +| `status` | ModStatus | 项目状态（见 ModStatus 附表） | +| `downloadCount` | int64 | 下载总次数 | +| `isFeatured` | boolean | 是否为精选项目 | +| `primaryCategoryId` | int32 | 作者选择的主分类 ID | +| `categories` | Category[] | 关联的分类列表（见 Category 附表） | +| `classId` | int32 \| null | 所属 class ID | +| `authors` | ModAuthor[] | 作者列表（见 ModAuthor 附表） | +| `logo` | ModAsset | Logo 资源（见 ModAsset 附表） | +| `screenshots` | ModAsset[] | 截图资源列表（见 ModAsset 附表） | +| `mainFileId` | int32 | 主文件 ID | +| `latestFiles` | File[] | 最新文件列表（File 定义详见 get.md） | +| `latestFilesIndexes` | FileIndex[] | 最新文件索引（见 FileIndex 附表） | +| `latestEarlyAccessFilesIndexes` | FileIndex[] | 最新抢先体验文件索引（见 FileIndex 附表） | +| `dateCreated` | string (date-time) | 创建时间（ISO 8601） | +| `dateModified` | string (date-time) | 最后修改时间（ISO 8601） | +| `dateReleased` | string (date-time) | 发布时间（ISO 8601） | +| `allowModDistribution` | boolean \| null | 是否允许分发 | +| `gamePopularityRank` | int32 | 游戏内热门排名 | +| `isAvailable` | boolean | 是否可被搜索到（实验性、已删除或仅有 Alpha 文件时可能为 false） | +| `thumbsUpCount` | int32 | 点赞数 | +| `rating` | number (decimal) \| null | 评分 | + +--- + +## 子类型 + +### ModLinks + +| 字段 | 类型 | 说明 | +|------|------|------| +| `websiteUrl` | string | 官网链接 | +| `wikiUrl` | string | Wiki 链接 | +| `issuesUrl` | string | Issue 追踪链接 | +| `sourceUrl` | string | 源码仓库链接 | + +### ModAuthor + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 作者 ID | +| `name` | string | 作者名 | +| `url` | string | 作者页面 URL | + +### ModAsset + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 资源 ID | +| `modId` | int32 | 所属项目 ID | +| `title` | string | 资源标题 | +| `description` | string | 资源描述 | +| `thumbnailUrl` | string | 缩略图 URL | +| `url` | string | 原图 URL | + +### Category + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 分类 ID | +| `gameId` | int32 | 关联的游戏 ID | +| `name` | string | 分类名称 | +| `slug` | string | URL 中的分类标识 | +| `url` | string | 分类页面 URL | +| `iconUrl` | string | 分类图标 URL | +| `dateModified` | string (date-time) | 最后修改时间（ISO 8601） | +| `isClass` | boolean \| null | 是否为顶层分类（可包含其他分类） | +| `classId` | int32 \| null | 所属 class ID | +| `parentCategoryId` | int32 \| null | 父分类 ID | +| `displayIndex` | int32 \| null | 显示排序索引 | + +### FileIndex + +| 字段 | 类型 | 说明 | +|------|------|------| +| `gameVersion` | string | 游戏版本 | +| `fileId` | int32 | 文件 ID | +| `filename` | string | 文件名 | +| `releaseType` | FileReleaseType | 发布类型（见 FileReleaseType 枚举） | +| `gameVersionTypeId` | int32 \| null | 版本类型 ID | +| `modLoader` | ModLoaderType | Mod Loader 类型（见 ModLoaderType 枚举） | + +--- + +## 枚举 + +### ModStatus + +| 值 | 含义 | +|----|------| +| 1 | New | +| 2 | ChangesRequired | +| 3 | UnderSoftReview | +| 4 | Approved | +| 5 | Rejected | +| 6 | ChangesMade | +| 7 | Inactive | +| 8 | Abandoned | +| 9 | Deleted | +| 10 | UnderReview | + +### FileReleaseType + +| 值 | 含义 | +|----|------| +| 1 | Release | +| 2 | Beta | +| 3 | Alpha | + +### FileRelationType + +| 值 | 含义 | +|----|------| +| 1 | EmbeddedLibrary | +| 2 | OptionalDependency | +| 3 | RequiredDependency | +| 4 | Tool | +| 5 | Incompatible | +| 6 | Include | + +### FileStatus + +| 值 | 含义 | +|----|------| +| 1 | Processing | +| 2 | ChangesRequired | +| 3 | UnderReview | +| 4 | Approved | +| 5 | Rejected | +| 6 | MalwareDetected | +| 7 | Deleted | +| 8 | Archived | +| 9 | Testing | +| 10 | Released | +| 11 | ReadyForReview | +| 12 | Deprecated | +| 13 | Baking | +| 14 | AwaitingPublishing | +| 15 | FailedPublishing | +| 16 | Cooking | +| 17 | Cooked | +| 18 | UnderManualReview | +| 19 | ScanningForMalware | +| 20 | ProcessingFile | +| 21 | PendingRelease | +| 22 | ReadyForCooking | +| 23 | PostProcessing | + +### HashAlgo + +| 值 | 含义 | +|----|------| +| 1 | Sha1 | +| 2 | Md5 | + +### ModLoaderType + +| 值 | 含义 | +|----|------| +| 0 | Any | +| 1 | Forge | +| 2 | Cauldron | +| 3 | LiteLoader | +| 4 | Fabric | +| 5 | Quilt | +| 6 | NeoForge | diff --git a/docs/curseforge/get.md b/docs/curseforge/get.md index dfaf230..4c1da06 100644 --- a/docs/curseforge/get.md +++ b/docs/curseforge/get.md @@ -49,10 +49,10 @@ GET https://api.curseforge.com/v1/mods/{modId}/files "isAvailable": true, // 是否可下载 "displayName": "My Mod v1.0", // 显示名称 "fileName": "my-mod-1.0.jar", // 文件名 - "releaseType": 1, // 1=Release, 2=Beta, 3=Alpha - "fileStatus": 10, // 文件状态（见附表） + "releaseType": 1, // FileReleaseType + "fileStatus": 10, // FileStatus "hashes": [ - { "value": "abc123...", "algo": 1 } // algo: 1=Sha1, 2=Md5 + { "value": "abc123...", "algo": 1 } // FileHash ], "fileDate": "2025-01-01T00:00:00Z", // 文件时间戳 "fileLength": 1048576, // 文件大小（字节） @@ -72,7 +72,7 @@ GET https://api.curseforge.com/v1/mods/{modId}/files "dependencies": [ // 依赖关系 { "modId": 123, // 依赖的项目 ID - "relationType": 3 // 关系类型（见附表） + "relationType": 3 // FileRelationType } ], "exposeAsAlternative": false, @@ -97,11 +97,9 @@ GET https://api.curseforge.com/v1/mods/{modId}/files } ``` ---- +### 枚举值 -## 附表 - -### releaseType +**FileReleaseType** | 值 | 含义 | |----|------| @@ -109,7 +107,7 @@ GET https://api.curseforge.com/v1/mods/{modId}/files | 2 | Beta | | 3 | Alpha | -### relationType +**FileRelationType** | 值 | 含义 | |----|------| @@ -120,11 +118,114 @@ GET https://api.curseforge.com/v1/mods/{modId}/files | 5 | Incompatible | | 6 | Include | -### fileStatus（常用值） +**FileStatus** | 值 | 含义 | |----|------| | 1 | Processing | +| 2 | ChangesRequired | +| 3 | UnderReview | | 4 | Approved | +| 5 | Rejected | +| 6 | MalwareDetected | +| 7 | Deleted | +| 8 | Archived | +| 9 | Testing | | 10 | Released | +| 11 | ReadyForReview | | 12 | Deprecated | +| 13 | Baking | +| 14 | AwaitingPublishing | +| 15 | FailedPublishing | +| 16 | Cooking | +| 17 | Cooked | +| 18 | UnderManualReview | +| 19 | ScanningForMalware | +| 20 | ProcessingFile | +| 21 | PendingRelease | +| 22 | ReadyForCooking | +| 23 | PostProcessing | + +**HashAlgo** + +| 值 | 含义 | +|----|------| +| 1 | Sha1 | +| 2 | Md5 | + +--- + +## Schemas + +### File + +响应中 `data[]` 的元素类型。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | int32 | 文件 ID | +| `gameId` | int32 | 所属游戏 ID | +| `modId` | int32 | 所属项目 ID | +| `isAvailable` | boolean | 是否可下载 | +| `displayName` | string | 显示名称 | +| `fileName` | string | 文件名 | +| `releaseType` | FileReleaseType | 发布类型 | +| `fileStatus` | FileStatus | 文件状态 | +| `hashes` | FileHash[] | 文件哈希列表 | +| `fileDate` | string(date-time) | 文件时间戳 | +| `fileLength` | int64 | 文件大小（字节） | +| `downloadCount` | int64 | 下载次数 | +| `fileSizeOnDisk` | int64 \| null | 磁盘占用 | +| `downloadUrl` | string | 下载地址 | +| `gameVersions` | string[] | 关联的游戏版本字符串列表 | +| `sortableGameVersions` | SortableGameVersion[] | 排序用版本信息 | +| `dependencies` | FileDependency[] | 依赖关系 | +| `exposeAsAlternative` | boolean \| null | 是否暴露为替代版本 | +| `parentProjectFileId` | int32 \| null | 父项目文件 ID | +| `alternateFileId` | int32 \| null | 替代文件 ID | +| `isServerPack` | boolean \| null | 是否为服务端包 | +| `serverPackFileId` | int32 \| null | 服务端包文件 ID | +| `isEarlyAccessContent` | boolean \| null | 是否为抢先体验内容 | +| `earlyAccessEndDate` | string(date-time) \| null | 抢先体验结束日期 | +| `fileFingerprint` | int64 | 文件指纹 | +| `modules` | FileModule[] | 文件模块列表 | + +### FileHash + +| 字段 | 类型 | 说明 | +|------|------|------| +| `value` | string | 哈希值 | +| `algo` | int | 哈希算法（见 HashAlgo 枚举） | + +### FileDependency + +| 字段 | 类型 | 说明 | +|------|------|------| +| `modId` | int32 | 依赖的项目 ID | +| `relationType` | int | 关系类型（见 FileRelationType 枚举） | + +### FileModule + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | string | 模块名 | +| `fingerprint` | int64 | 模块指纹 | + +### SortableGameVersion + +| 字段 | 类型 | 说明 | +|------|------|------| +| `gameVersionName` | string | 原始版本名（如 `1.5b`） | +| `gameVersionPadded` | string | 补齐版本号（如 `0000000001.0000000005`），用于排序 | +| `gameVersion` | string | 清洗后的版本号（如 `1.5`） | +| `gameVersionReleaseDate` | string(date-time) | 版本发布日期 | +| `gameVersionTypeId` | int32 \| null | 游戏版本类型 ID | + +### Pagination + +| 字段 | 类型 | 说明 | +|------|------|------| +| `index` | int32 | 本次返回的起始索引（从 0 开始） | +| `pageSize` | int32 | 请求的页大小 | +| `resultCount` | int32 | 本次实际返回数量 | +| `totalCount` | int64 | 符合条件的总数量 | diff --git a/docs/curseforge/index.md b/docs/curseforge/index.md new file mode 100644 index 0000000..24f24db --- /dev/null +++ b/docs/curseforge/index.md @@ -0,0 +1,79 @@ +# CurseForge REST API 文档 + +> 来源：https://docs.curseforge.com/rest-api/ +> +> API 基础地址：`https://api.curseforge.com`，认证方式：Header `x-api-key: ` + +--- + +## 通用说明 + +- 分页上限：最大 pageSize 为 50，总结果上限 10,000（`index + pageSize <= 10,000`） +- 除非特别说明，所有 `int32` 响应均为无符号整数 + +--- + +## 端点总览 + +### Games +| 方法 | 路径 | 说明 | 详见 | +|------|------|------|------| +| GET | `/v1/games` | 获取所有可用游戏 | — | +| GET | `/v1/games/{gameId}` | 获取单个游戏 | — | +| GET | `/v1/games/{gameId}/versions` | 获取游戏的所有版本（V1） | — | +| GET | `/v2/games/{gameId}/versions` | 获取游戏的所有版本（V2） | — | +| GET | `/v1/games/{gameId}/version-types` | 获取游戏的版本类型 | — | + +### Categories +| 方法 | 路径 | 说明 | 详见 | +|------|------|------|------| +| GET | `/v1/categories` | 获取分类（class/category） | — | + +### Mods +| 方法 | 路径 | 说明 | 详见 | +|------|------|------|------| +| GET | `/v1/mods/search` | 搜索项目 | — | +| GET | `/v1/mods/{modId}` | 获取单个项目 | [get-mod.md](get-mod.md) | +| POST | `/v1/mods` | 批量获取项目 | — | +| POST | `/v1/mods/featured` | 获取精选/热门/最近更新 | — | +| GET | `/v1/mods/{modId}/description` | 获取项目描述（HTML） | — | + +### Files +| 方法 | 路径 | 说明 | 详见 | +|------|------|------|------| +| GET | `/v1/mods/{modId}/files/{fileId}` | 获取单个文件 | — | +| GET | `/v1/mods/{modId}/files` | 获取项目的所有文件 | [get.md](get.md) | +| POST | `/v1/mods/files` | 批量获取文件 | — | +| GET | `/v1/mods/{modId}/files/{fileId}/changelog` | 获取文件更新日志（HTML） | — | +| GET | `/v1/mods/{modId}/files/{fileId}/download-url` | 获取文件下载链接 | — | + +### Fingerprints +| 方法 | 路径 | 说明 | 详见 | +|------|------|------|------| +| POST | `/v1/fingerprints/{gameId}` | 精确指纹匹配（按游戏） | — | +| POST | `/v1/fingerprints` | 精确指纹匹配 | — | +| POST | `/v1/fingerprints/fuzzy/{gameId}` | 模糊指纹匹配（按游戏） | — | +| POST | `/v1/fingerprints/fuzzy` | 模糊指纹匹配 | — | + +### Minecraft +| 方法 | 路径 | 说明 | 详见 | +|------|------|------|------| +| GET | `/v1/minecraft/version` | 获取 Minecraft 版本列表 | [get-meta.md](get-meta.md) | +| GET | `/v1/minecraft/version/{versionString}` | 获取特定 Minecraft 版本 | — | +| GET | `/v1/minecraft/modloader` | 获取 ModLoader 列表 | — | +| GET | `/v1/minecraft/modloader/{name}` | 获取特定 ModLoader | — | + +--- + +## 文件说明 + +本目录下各文件用途： + +| 文件 | 说明 | +|------|------| +| `index.md` | 总览页面，列出所有 REST API 端点及本文档的文件索引 | +| `all-schemas.md` | 所有 REST API 涉及的 Schema 定义和枚举值完整列表。一般不需要读——大多数 Schema 已在各端点文档中内联 | +| `get-mod.md` | `GET /v1/mods/{modId}` 端点详解，包含请求示例、响应字段及子类型说明 | +| `get.md` | `GET /v1/mods/{modId}/files` 端点详解，包含 File Schema、枚举值及分页响应 | +| `get-meta.md` | `GET /v1/minecraft/version` 端点详解，获取 Minecraft 版本列表 | +| `upload.md` | 上传相关 API（base URL 为 `https://minecraft.curseforge.com`），包括 Game Version Types、Game Versions、文件上传/更新及 Maven 端点 |