# 文档 API

基于代码生成全面的 API 文档。

> \[!NOTE]
>
> * Copilot 提示文件为 公共预览版，可能随时更改。 提示文件仅适用于 VS Code、Visual Studio 和 JetBrains IDE。请查看 [关于自定义GitHub Copilot 响应](/zh/copilot/concepts/prompting/response-customization#about-prompt-files)。
> * 如需获取社区提供的有关特定语言和场景的提示文件示例，请参阅[出色的 GitHub Copilot 自定义内容](https://github.com/github/awesome-copilot/blob/main/docs/README.prompts.md)仓库。

此提示文件通过分析 API 代码以及创建标准化的计算机可读文档，为 REST API 终结点生成 OpenAPI 3.0 规范。

## OpenAPI 规范提示

```text copy
---
agent: 'agent'
description: 'Generate OpenAPI 3.0 specification for API endpoints'
---

## Task

Analyze the API endpoint code and generate a valid OpenAPI 3.0 specification in YAML format.

## OpenAPI Structure

Generate a complete OpenAPI spec including:

1. **OpenAPI Header**
   - OpenAPI version (3.0.3)
   - API info (title, description, version)
   - Server configuration

2. **Path Definitions**
   - HTTP method and path
   - Operation summary and description
   - Tags for organization

3. **Parameters Schema**
   - Path parameters with type validation
   - Query parameters with constraints and defaults
   - Request body schema using proper JSON Schema
   - Required vs optional parameters

4. **Response Schemas**
   - Success responses (200, 201, etc.) with schema definitions
   - Error responses (400, 401, 404, 500) with error schema
   - Content-Type specifications
   - Realistic example values

5. **Components Section**
   - Reusable schemas for request/response models
   - Security schemes (Bearer token, API key, etc.)
   - Common parameter definitions

## Requirements

- Generate valid OpenAPI 3.0.3 YAML that passes validation
- Use proper JSON Schema for all data models
- Include realistic example values, not placeholders
- Define reusable components to avoid duplication
- Add appropriate data validation (required fields, formats, constraints)
- Include security requirements where applicable

Focus on: ${input:endpoint_focus:Which specific endpoint or endpoints should be documented?}

Generate production-ready OpenAPI specification that can be used with Swagger UI, Postman, and code generators.
```

## 如何使用此提示文件

1. 将上述内容另存为 `document-api.prompt.md`，并将其保存在 `.github/prompts` 文件夹中。
2. 在 Visual Studio Code 中，显示 副驾驶聊天 视图，然后输入 `/document-api`。 （可选）也可以通过键入 `endpoint_focus=GET /activities` 等内容，指明要为其创建文档的具体终结点。

## 其他阅读材料

* Visual Studio Code 文档中的[使用 Visual Studio Code 中的提示文件](https://code.visualstudio.com/docs/copilot/customization/prompt-files) - 有关如何创建和使用提示文件的信息
* [关于自定义GitHub Copilot 响应](/zh/copilot/concepts/response-customization) - GitHub Copilot 中的响应自定义概述
* [出色的 GitHub Copilot 自定义内容](https://github.com/github/awesome-copilot/blob/main/docs/README.prompts.md) - 社区提供的自定义提示文件的仓库以及特定语言和场景的其他自定义内容