# FastGPT API Development

Defines FastGPT API inputs and outputs with zod schemas and OpenAPI docs.

- Repository: https://github.com/labring/FastGPT (29968 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add labring/FastGPT --skill api-development -g -a claude-code -y`
Codex: `npx skills add labring/FastGPT --skill api-development -g -a codex -y`
Cursor: `npx skills add labring/FastGPT --skill api-development -g -a cursor -y`
Gemini CLI: `npx skills add labring/FastGPT --skill api-development -g -a gemini-cli -y`

## Description

FastGPT API 开发规范。重点强调使用 zod schema 定义入参和出参,在 API 文档中声明路由信息,编写对应的 OpenAPI 文档,以及在 API 路由中使用 schema.parse 进行验证。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# FastGPT API 开发规范

> FastGPT 项目 API 路由开发的标准化指南,确保 API 的一致性、类型安全和文档完整性。

## 何时使用此技能

- 开发新的 Next.js API 路由
- 修改现有 API 的入参或出参
- 需要 API 类型定义和文档
- 审查 API 相关代码

## 核心原则

### 🔴 必须遵守的规则

1. **API 中实际存在的业务入参和业务出参必须使用 zod schema 定义；无入参或空成功响应不创建空 Schema**
2. **已定义的 schema 必须导出对应的 TypeScript 类型**
3. **必须在 schema 文件头部声明 API 信息(路由、方法、描述、标签)，一次性管理员升级/清洗能力除外**
4. **实际存在的入参必须使用 `parseApiInput` 验证；完全无入参时不做空 Query/Body Schema 校验**
5. **实际存在业务数据的函数返回值必须使用 schema.parse() 验证；空成功响应直接返回 `undefined`，不做空 Schema 校验**
6. **必须编写完整的 OpenAPI 文档，一次性管理员升级/清洗能力除外**

### 管理员升级与清洗能力的文档豁免

仅供系统管理员执行、用于一次性升级、迁移、修复或数据清洗的内部接口和脚本，不属于产品 API，不要求：

- 在 `packages/global/openapi/` 声明接口文档；
- 注册 OpenAPI Path；
- 编写 API 头部路由、方法、描述和标签信息。

豁免只针对文档，不豁免安全和校验要求：

- 管理员接口必须使用 `authSystemAdmin` 鉴权；
- 实际存在的 API 入参必须使用 Zod Schema 和 `parseApiInput`，完全无入参时不创建空 Schema；
- 实际存在业务数据的返回值必须使用 Zod Schema 校验，空成功响应直接返回 `undefined`；
- 数据清洗默认使用 dry-run，显式确认后才能写入，并输出成功、跳过和失败统计；
- 清洗逻辑应可重复执行，无法安全修复的数据必须跳过并报告，不得静默填入猜测值。

常规管理员产品接口（例如模型配置 CRUD、用户管理和系统配置）不因仅管理员可用而获得豁免，仍需按标准 API 流程维护文档。

## 开发流程

### 步骤 1: 定义 Zod Schema 并声明 API

**文件位置**: `packages/global/openapi/[module]/[api].ts`

**文件头部必须声明 API 信息**:

```typescript
import { z } from 'zod';

/* ============================================================================
 * API: 获取应用对话日志列表
 * Route: POST /api/core/app/logs/list
 * Method: POST
 * Description: 获取指定应用的对话日志列表,支持分页和多种筛选条件
 * Tags: ['App', 'Log', 'Read']
 * ============================================================================ */

The rest: https://github.com/labring/FastGPT/blob/HEAD/.agents/skills/system/api-development/SKILL.md