swagger-docs
Swagger/OpenAPIドキュメントの作成・更新、新しいエンドポイントの文書化、既存のAPIドキュメントの完全性確認、またはコードからのOpenAPI仕様生成を行う場合に使用します。内部専用APIで外部利用者がおらず、ドキュメント要件がない場合はスキップしてください。エンドポイント命名、HTTP規約、バージョニング戦略などのAPI設計判断を行う場合はスキップし、代わりにapi-designを使用してください。
description の原文を見る
Use when writing or updating Swagger/OpenAPI docs, documenting new endpoints, reviewing existing API docs for completeness, or generating OpenAPI spec from code. Skip when the API is internal-only with no external consumers and no doc requirement. Skip when making API design decisions (endpoint naming, HTTP conventions, versioning strategy) — use api-design instead.
SKILL.md 本文
OpenAPI 3.0 ドキュメンテーション
チーム標準: OpenAPI Specification 3.0.x OAS 3.1 および 3.2 はより新しいバージョンで、JSON Schema との完全な対応があります。ツールのサポートが成熟した時点で移行してください。 以下のルールは仕様（OAS 3.0.x で必須 — 違反するとツールが動作しない）または慣例（OpenAPI Initiative の業界ベストプラクティス — 違反は開発者体験を損なう）のいずれかです。
コア原則
ドキュメンテーションが完全な状態とは、コードベースを見たことのない開発者が以下のことができる状態です：
summaryとdescriptionだけで各エンドポイントが何をするのかを理解できる- リクエストスキーマとサンプルから何を送信すべきかが正確にわかる
- 実装者に聞かなくても、エラーを含むすべての可能なレスポンスがわかる
ネーミングルール (慣例)
| 要素 | 慣例 | ルール |
|---|---|---|
operationId | camelCase 動詞+名詞 | スペッ |
...
詳細情報
- 作者
- phananhtuan09
- ライセンス
- 不明
- 最終更新
- 2026/5/7
Source: https://github.com/phananhtuan09/ai-agent-workflow / ライセンス: 未指定