diff --git a/docs/modrinth/get-project.md b/docs/modrinth/get-project.md new file mode 100644 index 0000000..0e8d342 --- /dev/null +++ b/docs/modrinth/get-project.md @@ -0,0 +1,264 @@ +# Get Project + +获取 Modrinth 上的单个或多个 project 的基本数据。 + +--- + +## GET `/project/{id|slug}` + +获取单个 project 的完整信息。 + +### 路径参数 + +| 参数 | 位置 | 类型 | 必填 | 说明 | +|------|------|------|------|------| +| `id\|slug` | path | `string` | ✅ | Project 的 ID（base62 编码）或 slug（用于自定义 URL）。 | + +### 响应 `200 OK` + +返回 [`Project`](#project-模型) 对象。 + +### 响应 `404 Not Found` + +指定的 project 不存在或无权限访问。 + +--- + +## GET `/projects` + +批量获取多个 project 的完整信息。 + +### 查询参数 + +| 参数 | 位置 | 类型 | 必填 | 说明 | +|------|------|------|------|------| +| `ids` | query | `string` | ✅ | 以 JSON 数组格式指定要获取的 project ID 或 slug。例如 `["AABBCCDD", "my_project"]`。 | + +### 响应 `200 OK` + +返回 [`Project`](#project-模型) 对象数组。 + +--- + +## Project 模型 + +`Project` 继承自多个层级 schema，完整字段如下。 + +> **🔗 Schema 继承关系:** `Project` = `NonSearchProject` + `ServerRenderedProject` + 自身字段 +> +> 其中 `NonSearchProject` 和 `ServerRenderedProject` 均继承自 `BaseProject`。 + +``` + +Project +├── BaseProject (基础信息) +│ ├── slug +│ ├── title +│ ├── description +│ ├── categories +│ ├── client_side +│ └── server_side +├── NonSearchProject (非搜索专属字段) +│ ├── body +│ ├── status +│ ├── requested_status +│ ├── additional_categories +│ ├── issues_url +│ ├── source_url +│ ├── wiki_url +│ ├── discord_url +│ └── donation_urls +├── ServerRenderedProject (服务端渲染字段) +│ ├── project_type +│ ├── downloads +│ ├── icon_url +│ ├── color +│ ├── thread_id +│ └── monetization_status +└── Project (自身字段) + ├── id + ├── team + ├── body_url ⚠️ + ├── moderator_message ⚠️ + ├── published + ├── updated + ├── approved + ├── queued + ├── followers + ├── license + ├── versions + ├── game_versions + ├── loaders + └── gallery + +``` + +### 字段一览 + +| 字段 | 类型 | 来源 | 说明 | +|------|------|------|------| +| `id` | `string` | Project | Project ID（base62 编码）。 | +| `slug` | `string` | BaseProject | 用于自定义 URL 的简短标识符，正则 `^[\w!@$().`+,"'-]{3,64}$`。 | +| `title` | `string` | BaseProject | Project 名称或标题。 | +| `description` | `string` | BaseProject | 简短描述。 | +| `body` | `string` | NonSearchProject | 长描述（支持 Markdown）。 | +| `categories` | `string[]` | BaseProject | 主分类列表。 | +| `additional_categories` | `string[]` | NonSearchProject | 附加分类（可搜索但非主要）。 | +| `client_side` | `string` | BaseProject | 客户端支持类型。`required` / `optional` / `unsupported` / `unknown`。 | +| `server_side` | `string` | BaseProject | 服务端支持类型。`required` / `optional` / `unsupported` / `unknown`。 | +| `project_type` | `string` | ServerRenderedProject | 项目类型。`mod` / `modpack` / `resourcepack` / `shader`。 | +| `downloads` | `integer` | ServerRenderedProject | 总下载次数。 | +| `followers` | `integer` | Project | 关注者数量。 | +| `status` | `string` | NonSearchProject | 项目状态：`approved` / `archived` / `rejected` / `draft` / `unlisted` / `processing` / `withheld` / `scheduled` / `private` / `unknown`。 | +| `requested_status` | `string` ⚠️ | NonSearchProject | 申请中的状态。`approved` / `archived` / `unlisted` / `private` / `draft`。可为 `null`。 | +| `license` | [`ProjectLicense`](#projectlicense) | Project | 许可证信息。 | +| `team` | `string` | Project | 拥有此 project 的团队 ID。 | +| `published` | `string` (ISO-8601) | Project | 发布日期。 | +| `updated` | `string` (ISO-8601) | Project | 最后更新日期。 | +| `approved` | `string` (ISO-8601) ⚠️ | Project | 审核通过日期。可为 `null`。 | +| `queued` | `string` (ISO-8601) ⚠️ | Project | 提交审核日期。可为 `null`。 | +| `icon_url` | `string` ⚠️ | ServerRenderedProject | 图标 URL。可为 `null`。 | +| `color` | `integer` ⚠️ | ServerRenderedProject | 从图标自动生成的 RGB 颜色值。可为 `null`。 | +| `thread_id` | `string` | ServerRenderedProject | 关联的审核线程 ID。 | +| `monetization_status` | `string` | ServerRenderedProject | 变现状态。`monetized` / `demonetized` / `force-demonetized`。 | +| `issues_url` | `string` ⚠️ | NonSearchProject | 问题跟踪链接。可为 `null`。 | +| `source_url` | `string` ⚠️ | NonSearchProject | 源代码链接。可为 `null`。 | +| `wiki_url` | `string` ⚠️ | NonSearchProject | Wiki 链接。可为 `null`。 | +| `discord_url` | `string` ⚠️ | NonSearchProject | Discord 邀请链接。可为 `null`。 | +| `donation_urls` | [`ProjectDonationURL[]`](#projectdonationurl) | NonSearchProject | 捐赠链接列表。 | +| `body_url` | `string` ⚠️ ⛔ | Project | 已弃用，始终为 `null`。 | +| `moderator_message` | [`ModeratorMessage`](#moderatormessage) ⛔ | Project | 已弃用，始终为 `null`。 | +| `versions` | `string[]` | Project | 所有版本 ID 列表（`draft` 状态时为空）。 | +| `game_versions` | `string[]` | Project | 支持的 Minecraft 版本列表。 | +| `loaders` | `string[]` | Project | 支持的模组加载器列表。 | +| `gallery` | [`GalleryImage[]`](#galleryimage) | Project | 图库图片列表。 | + +> ⚠️ 表示可为 `null`。⛔ 表示已弃用。 + +--- + +### ProjectLicense + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | `string` | SPDX 许可证 ID（如 `LGPL-3.0-or-later`）。 | +| `name` | `string` | 许可证全名（如 `GNU Lesser General Public License v3 or later`）。 | +| `url` | `string` ⚠️ | 许可证文本 URL，可为 `null`。 | + +### ProjectDonationURL + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | `string` | 捐赠平台 ID（如 `patreon`）。 | +| `platform` | `string` | 捐赠平台名称（如 `Patreon`）。 | +| `url` | `string` | 捐赠链接。 | + +### GalleryImage + +| 字段 | 类型 | 说明 | +|------|------|------| +| `url` | `string` | 图片 URL。 | +| `featured` | `boolean` | 是否为精选图片。 | +| `title` | `string` ⚠️ | 图片标题，可为 `null`。 | +| `description` | `string` ⚠️ | 图片描述，可为 `null`。 | +| `created` | `string` (ISO-8601) | 创建日期。 | +| `ordering` | `integer` | 排序序号（先按此字段排，再按标题字母序排）。 | + +### ModeratorMessage + +> ⛔ 已弃用，始终为 `null`。 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `message` | `string` | 审核员留言。 | +| `body` | `string` ⚠️ | 留言详细内容，可为 `null`。 | + +--- + +## 示例 + +### 请求 - 获取单个 project + +```bash +curl -X GET "https://api.modrinth.com/v2/project/my_project" +``` + +### 响应 + +```json +{ + "id": "AABBCCDD", + "slug": "my_project", + "team": "MMNNOOPP", + "title": "My Project", + "description": "A short description", + "body": "A long body describing my project in detail", + "categories": ["technology", "adventure", "fabric"], + "additional_categories": ["utility"], + "client_side": "required", + "server_side": "optional", + "project_type": "mod", + "status": "approved", + "requested_status": null, + "downloads": 52341, + "followers": 1203, + "license": { + "id": "MIT", + "name": "MIT License", + "url": "https://opensource.org/licenses/MIT" + }, + "published": "2023-03-15T10:30:00Z", + "updated": "2024-01-20T14:22:00Z", + "approved": "2023-03-15T12:00:00Z", + "queued": null, + "icon_url": "https://cdn.modrinth.com/data/AABBCCDD/icon.png", + "color": 8703084, + "thread_id": "TTUUVVWW", + "monetization_status": "monetized", + "issues_url": "https://github.com/my_user/my_project/issues", + "source_url": "https://github.com/my_user/my_project", + "wiki_url": null, + "discord_url": "https://discord.gg/AaBbCcDd", + "donation_urls": [ + { + "id": "patreon", + "platform": "Patreon", + "url": "https://www.patreon.com/my_user" + } + ], + "body_url": null, + "moderator_message": null, + "versions": ["IIJJKKLL", "QaRSSTT"], + "game_versions": ["1.19", "1.19.1", "1.19.2", "1.19.3"], + "loaders": ["forge", "fabric", "quilt"], + "gallery": [ + { + "url": "https://cdn.modrinth.com/data/AABBCCDD/images/009b7d8d6e8bf04968a29421117c59b3efe2351a.png", + "featured": true, + "title": "My awesome screenshot!", + "description": "This awesome screenshot shows all of the blocks in my mod!", + "created": "2023-06-01T08:15:00Z", + "ordering": 0 + } + ] +} +``` + +### 请求 - 批量获取多个 project + +```bash +curl -X GET "https://api.modrinth.com/v2/projects?ids=%5B%22AABBCCDD%22%2C%22my_project%22%5D" +``` + +> URL 编码后的 `ids` 参数值为 `["AABBCCDD","my_project"]`。 + +### 响应 + +```json +[ + { "...": "..." }, + { "...": "..." } +] +``` + +返回 `Project` 对象数组，每个对象结构与单个获取一致。