# ドキュメント API

コードから包括的な API ドキュメントを生成します。

> \[!NOTE]
> \*
> Copilot プロンプト ファイルはパブリック プレビューにあり、変更される可能性があります。
> プロンプト ファイルは、VS Code、Visual Studio、および JetBrains IDE でのみ使用できます。
> [「AUTOTITLE」を](/ja/copilot/concepts/prompting/response-customization#about-prompt-files)参照してください。
>
> * コミュニティが提供する特定の言語とシナリオのプロンプト ファイルの例については、「 [Awesome GitHub Copilot Customizations](https://awesome-copilot.github.com) 」サイトを参照してください。

このプロンプト ファイルでは、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 で Copilot Chat ビューに、「`/document-api`」と入力します。 必要な場合は、「`endpoint_focus=GET /activities`」と入力して、ドキュメント化が必要な特定のエンドポイントを指定することもできます。

## 参考資料

* [
  Visual Studio Code でプロンプト ファイルを使用](https://code.visualstudio.com/docs/copilot/customization/prompt-files) - Visual Studio Code ドキュメントの、プロンプト ファイルの作成方法と使用方法に関する情報
* [GitHub Copilotの応答をカスタマイズする方法](/ja/copilot/concepts/prompting/response-customization) - GitHub Copilot での応答カスタマイズの概要
* [優れた GitHub Copilot カスタマイズ](https://github.com/github/awesome-copilot/blob/main/docs/README.prompts.md) - コミュニティに投稿されたカスタム プロンプト ファイルや、特定の言語やシナリオ向けのその他のカスタマイズのリポジトリ