# API Doc Comparator Prompt

> Compare two API docs to find endpoint and parameter changes without inferring compatibility.

## Install

Copy the content below into your project:

# API Doc Comparator Prompt

Compare two API docs to find endpoint and parameter changes without inferring compatibility.

### Start here

1. **Prepare Input**: Copy the text of your old API documentation into `SOURCE_DOCS` and the new version into `TARGET_DOCS`.
2. **Paste Prompt**: Copy the complete prompt below and paste it into an AI chat that accepts text input.
3. **Check Output**: Verify the AI returns a Markdown table listing endpoints, description changes, and parameter diffs. Ensure no compatibility assumptions are made unless explicitly stated in the source text.

**Source reviewed; runtime not tested**

### Introduction

This original prompt is designed for developers and technical writers who need to compare software API documentation versions safely. It enforces strict adherence to provided text, preventing the AI from hallucinating migration paths or backward compatibility details. The output is a structured Markdown table highlighting specific differences in endpoints and parameters.

### Prerequisites and Limitations

- You must have the raw text of both the "Source" (old) and "Target" (new) API documentation.
- This tool does not execute code or connect to live APIs; it analyzes text only.
- Privacy: Do not paste sensitive internal keys or secrets into the prompt.
- Limitations: If the documentation lacks detail on parameters, the AI will mark them as "Not Stated" rather than guessing.

### FAQ

**Q: What if the new documentation removes an endpoint?**
A: The prompt instructs the AI to list all unique endpoints found in either document. If an endpoint exists in Source but not Target, it should be noted in the comparison, typically indicating removal or absence in the target context.

**Q: Can this prompt suggest code fixes?**
A: No. The critical constraint explicitly forbids inferring compatibility or suggesting migration scripts unless the text states them. It focuses solely on textual differences.

### Attribution

Original TokRepo prompt, CC BY 4.0. Based on general-purpose AI workspace templates.

## Complete reusable prompt

# Role: API Documentation Comparator

You are a precise technical analyst tasked with comparing two versions of software API documentation. Your goal is to identify differences in endpoint descriptions and parameter requirements between a "Source" version and a "Target" version.

**Critical Constraint:** Do NOT infer compatibility, backward compatibility, or migration paths unless explicitly stated in the text. If information is missing, mark it as "Not Stated." Do not use external knowledge about the API provider.

## Input Data
You will receive two blocks of text:
1. `[SOURCE_DOCS]`: The original or older documentation text.
2. `[TARGET_DOCS]`: The new or updated documentation text.

## Task Instructions

1. **Identify Endpoints**: Extract all unique API endpoints mentioned in either document. An endpoint is defined by its HTTP method (GET, POST, etc.) and path (e.g., `POST /users`).
2. **Compare Descriptions**: For each endpoint, compare the natural language description in Source vs. Target.
   - Note any additions, removals, or semantic changes in the purpose of the endpoint.
3. **Compare Parameters**: For each endpoint, list all required and optional parameters.
   - Compare names, types, and constraints (e.g., "required", "max length").
   - Highlight if a parameter was removed, added, or had its requirement status changed (e.g., Optional -> Required).
4. **Handle Missing Info**: If a parameter exists in one doc but not the other, explicitly state "Removed in Target" or "Added in Target." If the description is identical, note "No Change."

## Output Format

Produce a Markdown table with the following columns:
- **Endpoint**: The HTTP method and path.
- **Description Change**: Summary of textual differences in the endpoint's purpose. Use "No Change" if identical.
- **Parameter Changes**: A bulleted list of specific parameter diffs. Format: `[Param Name]: [Change Detail]`. If no parameters changed, use "None."
- **Compatibility Note**: ONLY if the text explicitly mentions breaking changes or deprecation. Otherwise, leave blank.

## Fictional Example Input

**[SOURCE_DOCS]**
`GET /v1/items`
Returns a list of items. 
Params:
- `limit` (integer, optional): Max number of items to return.

**[TARGET_DOCS]**
`GET /v1/items`
Returns a paginated list of items. 
Params:
- `limit` (integer, required): Max number of items to return. Default 10.
- `cursor` (string, optional): Pagination token.

## Fictional Example Output

| Endpoint | Description Change | Parameter Changes | Compatibility Note |
| :--- | :--- | :--- | :--- |
| GET /v1/items | Updated to specify "paginated" list. | • limit: Changed from Optional to Required. Added default value info.<br>• cursor: Added in Target. | |

## Pass/Fail Checks

Before finalizing, verify:
1. Did you include every endpoint found in EITHER source?
2. Did you avoid suggesting code fixes or migration scripts?
3. Are all parameter changes tied strictly to the provided text?
4. Is the output format exactly as specified (Markdown table)?

## Final Execution

Analyze the following inputs:

[SOURCE_DOCS]
{{user_source_docs}}

[TARGET_DOCS]
{{user_target_docs}}

## References and reuse

- [ChatGPT release notes](https://help.openai.com/en/articles/6825453-chatgpt-release-notes)

Original TokRepo prompt · [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). Reference documents retain their own rights.

---

<!-- ZH -->

# API 文档对比提示词

对比两份 API 文档，找出端点和参数变化，不推断兼容性。

### 开始使用

1. **准备输入**：将旧版 API 文档文本复制到 `SOURCE_DOCS`，新版文档文本复制到 `TARGET_DOCS`。
2. **粘贴提示词**：复制下方的完整提示词，粘贴到支持文本输入的 AI 聊天窗口中。
3. **检查结果**：确认 AI 返回了一个 Markdown 表格，列出了端点、描述变化和参数差异。确保除非源文本明确说明，否则未做兼容性假设。

**来源已审核；运行时未测试**

### 简介

此原创提示词专为需要安全比较软件 API 文档版本的开发人员和专业技术作家设计。它强制严格遵循提供的文本，防止 AI 虚构迁移路径或向后兼容细节。输出是一个结构化的 Markdown 表格，突出显示端点和参数的具体差异。

### 前提条件与限制

- 您必须拥有“源”（旧）和“目标”（新）API 文档的原始文本。
- 此工具不执行代码也不连接实时 API，仅分析文本。
- 隐私：请勿将敏感的内部密钥或机密信息粘贴到提示词中。
- 限制：如果文档缺乏参数详细信息，AI 会将其标记为“未说明”，而不是进行猜测。

### 常见问题

**问：如果新文档移除了某个端点怎么办？**
答：提示词指示 AI 列出在任一文档中发现的所有唯一端点。如果端点存在于源文档但不存在于目标文档，应在比较中指出，通常表明在目标上下文中已移除或缺失。

**问：此提示词能建议代码修复吗？**
答：不能。关键约束明确禁止推断兼容性或建议迁移脚本，除非文本中明确陈述。它仅关注文本差异。

### 致谢

TokRepo 原创提示词，CC BY 4.0。基于通用人工智能工作区模板。

## 完整可复制提示词

# 角色：API 文档对比器

您是一名精确的技术分析师，任务是比较两个版本的软件 API 文档。您的目标是识别“源”版本和“目标”版本之间端点描述和参数要求的差异。

**关键约束：** 除非文本中明确说明，否则不要推断兼容性、向后兼容性或迁移路径。如果信息缺失，请将其标记为“未说明”。不要使用关于 API 提供商的外部知识。

## 输入数据
您将收到两段文本：
1. `[SOURCE_DOCS]`：原始或较旧的文档文本。
2. `[TARGET_DOCS]`：新的或更新的文档文本。

## 任务说明

1. **识别端点**：提取任一文档中提到的所有唯一 API 端点。端点由其 HTTP 方法（GET、POST 等）和路径（例如 `POST /users`）定义。
2. **比较描述**：对于每个端点，比较源和目标中的自然语言描述。
   - 注意端点目的的任何添加、删除或语义变化。
3. **比较参数**：对于每个端点，列出所有必需和可选参数。
   - 比较名称、类型和约束（例如，“必需”、“最大长度”）。
   - 突出显示参数是否被移除、添加或其要求状态发生变化（例如，可选 -> 必需）。
4. **处理缺失信息**：如果某个参数存在于一个文档中而不在另一个文档中，请明确说明“在目标中已移除”或“在目标中已添加”。如果描述相同，请注明“无变化。”

## 输出格式

生成一个包含以下列的 Markdown 表格：
- **Endpoint (端点)**：HTTP 方法和路径。
- **Description Change (描述变化)**：端点目的中文本差异的摘要。如果相同，请使用“无变化”。
- **Parameter Changes (参数变化)**：具体参数差异的项目符号列表。格式：`[Param Name]: [Change Detail]`。如果没有参数变化，请使用“None.”。
- **Compatibility Note (兼容性说明)**：仅当文本明确提及破坏性变更或弃用时才填写。否则留空。

## 虚构示例输入

**[SOURCE_DOCS]**
`GET /v1/items`
返回项目列表。
Params:
- `limit` (integer, optional): 要返回的最大项目数。

**[TARGET_DOCS]**
`GET /v1/items`
返回分页的项目列表。
Params:
- `limit` (integer, required): 要返回的最大项目数。默认值为 10。
- `cursor` (string, optional): 分页令牌。

## 虚构示例输出

| Endpoint | Description Change | Parameter Changes | Compatibility Note |
| :--- | :--- | :--- | :--- |
| GET /v1/items | 更新以指定“分页”列表。 | • limit: 从可选变为必需。添加了默认值信息。<br>• cursor: 在目标中新增。 | |

## 通过/失败检查

在最终确定之前，请验证：
1. 您是否包含了在任一来源中发现的每一个端点？
2. 您是否避免了建议代码修复或迁移脚本？
3. 所有参数变化是否严格基于提供的文本？
4. 输出格式是否完全符合规定（Markdown 表格）？

## 最终执行

分析以下输入：

[SOURCE_DOCS]
{{user_source_docs}}

[TARGET_DOCS]
{{user_target_docs}}

## 参考资料与复用

- [ChatGPT release notes](https://help.openai.com/en/articles/6825453-chatgpt-release-notes)

TokRepo 原创提示词 · [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)。参考资料保留各自原有权利。

---
Source: https://tokrepo.com/en/workflows/api-doc-comparator-prompt-0844f24c
Author: Prompt Lab