apipost_smart_create

Generate API documentation from field lists for headers, query, body, cookies, and responses using structured data with real examples and clear descriptions.

Instructions

API接口文档生成器（字段列表驱动）。规则：responses 只传 fields，不传 data；headers/query/body/cookies 统一用字段列表，嵌套用 .，数组用 []；example 填真实值（不要 JSON 字符串）；所有字段含父级都必须写 desc，父级需显式声明。例如：{"key":"data","desc":"返回体","type":"object"},{"key":"data.user","desc":"用户","type":"object"},{"key":"data.user.id","desc":"用户ID","type":"integer","example":1}

Input Schema

TableJSON Schema

Name	Required	Description
`method`	Yes	HTTP方法
`url`	Yes	接口URL路径
`name`	Yes	接口名称
`parent_id`	No	父目录ID，使用"0"表示根目录，默认为"0"
`description`	No	接口详细描述（可选）
`headers`	No	Headers字段列表字符串，格式：[{"key":"X-Request-ID","type":"string","required":false,"example":"req-1","desc":"说明"}]
`query`	No	Query字段列表字符串，格式同上。嵌套用 .，数组用 []（如 meta.flags.debug 或 items[].id）。
`body`	No	Body字段列表字符串，仅用字段列表生成 raw/参数描述，example 用真实值，不要放 JSON 字符串。
`cookies`	No	Cookies字段列表字符串，格式同上。
`auth`	No	认证配置JSON字符串（可选）。格式：{"type":"bearer","bearer":{"key":"your_token"}}
`responses`	No	响应字段列表字符串（必填 fields），格式：[{"name":"成功","status":200,"fields":[{"key":"code","type":"integer","example":0,"desc":"状态码"},{"key":"data.items[].id","type":"string","example":"1"}]}]

Implementation Reference

src/index.ts:882-903 (registration)

Tool registration in the ListToolsRequestSchema handler, including name, description, and inputSchema.

{
    name: 'apipost_smart_create',
    description: 'API接口文档生成器（字段列表驱动）。规则：responses 只传 fields，不传 data；headers/query/body/cookies 统一用字段列表，嵌套用 .，数组用 []；example 填真实值（不要 JSON 字符串）；所有字段含父级都必须写 desc，父级需显式声明。例如：{"key":"data","desc":"返回体","type":"object"},{"key":"data.user","desc":"用户","type":"object"},{"key":"data.user.id","desc":"用户ID","type":"integer","example":1}',
    inputSchema: {
        type: 'object',
        properties: {
            method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'DELETE'], description: 'HTTP方法' },
            url: { type: 'string', description: '接口URL路径' },
            name: { type: 'string', description: '接口名称' },
            parent_id: { type: 'string', description: '父目录ID，使用"0"表示根目录，默认为"0"' },
            description: { type: 'string', description: '接口详细描述（可选）' },
            headers: { type: 'string', description: 'Headers字段列表字符串，格式：[{"key":"X-Request-ID","type":"string","required":false,"example":"req-1","desc":"说明"}]' },
            query: { type: 'string', description: 'Query字段列表字符串，格式同上。嵌套用 .，数组用 []（如 meta.flags.debug 或 items[].id）。' },
            body: { type: 'string', description: 'Body字段列表字符串，仅用字段列表生成 raw/参数描述，example 用真实值，不要放 JSON 字符串。' },
            cookies: { type: 'string', description: 'Cookies字段列表字符串，格式同上。' },
            auth: { type: 'string', description: '认证配置JSON字符串（可选）。格式：{"type":"bearer","bearer":{"key":"your_token"}}' },
            responses: { type: 'string', description: '响应字段列表字符串（必填 fields），格式：[{"name":"成功","status":200,"fields":[{"key":"code","type":"integer","example":0,"desc":"状态码"},{"key":"data.items[].id","type":"string","example":"1"}]}]' }
        },
        required: ['method', 'url', 'name'],
        additionalProperties: false
    }
},

src/index.ts:1395-1419 (handler)

The main execution logic for the apipost_smart_create tool: validates permissions, builds config from input args, generates API template, and creates the API via ApiPost endpoint.

case 'apipost_smart_create':
    if (!checkSecurityPermission('write')) {
        throw new Error(`🔒 安全模式 "${APIPOST_SECURITY_MODE}" 不允许创建操作。需要 "limited" 或 "full" 模式。`);
    }
    // 构建配置对象
    const { config } = buildApiConfig(args);
    const template = generateApiTemplate(args.method, args.url, args.name, config);
    template.project_id = currentWorkspace.projectId;
    // 设置父目录ID
    template.parent_id = args.parent_id || '0';
    const headerCount = config.headers?.length || 0;
    const queryCount = config.query?.length || 0;
    const bodyCount = config.body?.length || 0;
    const responseCount = config.responses?.length || 0;
    const createResult = await apiClient.post('/open/apis/create', template);
    if (createResult.data.code !== 0) {
        throw new Error(`创建失败: ${createResult.data.msg}`);
    }

    return {
        content: [{
                type: 'text',
                text: `API创建成功!\n名称: ${args.name}\n方法: ${args.method}\nURL: ${args.url}\nID: ${createResult.data.data.target_id}\n\n字段统计:\n• Headers: ${headerCount}个\n• Query参数: ${queryCount}个\n• Body参数: ${bodyCount}个\n• 响应示例: ${responseCount}个`
            }]
    };

src/index.ts:688-725 (helper)

Helper function to parse and validate input arguments into API config object, tracking which fields were provided.

function buildApiConfig(args) {
    const config = {};
    const providedFields = new Set();
    if (args.description !== undefined) {
        config.description = args.description;
        providedFields.add('description');
    }
    if (args.headers !== undefined) {
        config.headers = parseConfigParam(args.headers);
        ensureFieldsHaveDesc(config.headers, 'headers');
        providedFields.add('headers');
    }
    if (args.query !== undefined) {
        config.query = parseConfigParam(args.query);
        ensureFieldsHaveDesc(config.query, 'query');
        providedFields.add('query');
    }
    if (args.body !== undefined) {
        config.body = parseConfigParam(args.body);
        ensureFieldsHaveDesc(config.body, 'body');
        providedFields.add('body');
    }
    if (args.cookies !== undefined) {
        config.cookies = parseConfigParam(args.cookies);
        ensureFieldsHaveDesc(config.cookies, 'cookies');
        providedFields.add('cookies');
    }
    if (args.auth !== undefined) {
        config.auth = parseApiConfig(args.auth);
        providedFields.add('auth');
    }
    if (args.responses !== undefined) {
        config.responses = parseConfigParam(args.responses);
        ensureResponsesFieldsHaveDesc(config.responses);
        providedFields.add('responses');
    }
    return { config, providedFields };
}

src/index.ts:727-764 (helper)

Helper function that generates the full ApiPost API template object from method, url, name, and config.

function generateApiTemplate(method, url, name, config = {}) {
    return {
        target_id: generateId(),
        target_type: 'api',
        parent_id: '0',
        name,
        method,
        url: applyUrlPrefix(url),
        protocol: 'http/1.1',
        description: config.description || `${name} - ${method} ${url}`,
        version: 3,
        mark_id: 1,
        is_force: -1,
        request: {
            auth: config.auth || { type: 'inherit' },
            pre_tasks: config.pre_tasks || [],
            post_tasks: config.post_tasks || [],
            header: {
                parameter: convertParams(config.headers || [])
            },
            query: {
                query_add_equal: 1,
                parameter: convertParams(config.query || [])
            },
            body: buildBodySection(config.body || []),
            cookie: {
                cookie_encode: 1,
                parameter: convertParams(config.cookies || [])
            },
            restful: {
                parameter: convertParams(config.restful || [])
            }
        },
        response: normalizeResponses(config.responses, { useDefaultWhenMissing: true, keepEmpty: true, isCheckResult: 1 }),
        attribute_info: config.attribute_info || {},
        tags: config.tags || []
    };
}

src/index.ts:885-902 (schema)

Input schema definition for the apipost_smart_create tool, specifying parameters and validation rules.

inputSchema: {
    type: 'object',
    properties: {
        method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'DELETE'], description: 'HTTP方法' },
        url: { type: 'string', description: '接口URL路径' },
        name: { type: 'string', description: '接口名称' },
        parent_id: { type: 'string', description: '父目录ID，使用"0"表示根目录，默认为"0"' },
        description: { type: 'string', description: '接口详细描述（可选）' },
        headers: { type: 'string', description: 'Headers字段列表字符串，格式：[{"key":"X-Request-ID","type":"string","required":false,"example":"req-1","desc":"说明"}]' },
        query: { type: 'string', description: 'Query字段列表字符串，格式同上。嵌套用 .，数组用 []（如 meta.flags.debug 或 items[].id）。' },
        body: { type: 'string', description: 'Body字段列表字符串，仅用字段列表生成 raw/参数描述，example 用真实值，不要放 JSON 字符串。' },
        cookies: { type: 'string', description: 'Cookies字段列表字符串，格式同上。' },
        auth: { type: 'string', description: '认证配置JSON字符串（可选）。格式：{"type":"bearer","bearer":{"key":"your_token"}}' },
        responses: { type: 'string', description: '响应字段列表字符串（必填 fields），格式：[{"name":"成功","status":200,"fields":[{"key":"code","type":"integer","example":0,"desc":"状态码"},{"key":"data.items[].id","type":"string","example":"1"}]}]' }
    },
    required: ['method', 'url', 'name'],
    additionalProperties: false
}

ApiPost MCP