api-documenter

api-documenterスキルの概要

api-documenterでできること

api-documenter は、エージェントが API ドキュメントを OpenAPI/Swagger 仕様として作成・改善するのを支援するスキルです。REST スタイルの API 構成を主軸に、GraphQL についても軽く触れています。実務では、まっさらな状態から書き始めたり、汎用的な「API ドキュメントを書いて」というプロンプトに頼ったりするよりも、使える openapi.yaml を素早く用意したい場面で特に役立ちます。

api-documenterを使うべき人

api-documenter skill が特に向いているのは、エンドポイント、リクエスト/レスポンスの構造、認証方式、エラーハンドリングを、標準的で機械可読な形式で整理したい開発者、テクニカルライター、DX チーム、プラットフォームエンジニアです。後から Swagger UI、コード生成、バリデーション、レビューのワークフローにつなげたいチームにとって、api-documenter skill はとくに使い勝手があります。

実際に解決したい仕事

多くのユーザーがやりたいのは、単なる「ドキュメント執筆」ではありません。散在している API の知識を、レビュー・実装・公開に回せる程度に妥当な OpenAPI ドラフトへまとめることです。api-documenter が強いのは、API の挙動自体はすでに把握していて、それを構造化し、抜け漏れを減らし、整合性をそろえたいケースです。

なぜ単なるプロンプトよりこちらを選ぶのか

差別化ポイントは高度な自動化ではなく、作業の型が用意されていることです。リポジトリには次のような材料があります。

• references/openapi-template.yaml に OpenAPI 3.0.3 の明確な出発点
• scripts/generate_openapi.py にスターター生成スクリプト
• scripts/validate_openapi.py に簡易バリデーター
• 書式の迷いを減らすサンプル

そのため api-documenter usage は、実際の API 詳細を自分で与える必要はあるものの、場当たり的なプロンプトより再現性のある進め方にしやすいのが利点です。

このスキルが代わりにやってくれないこと

このスキルは、稼働中の API を自動検出したり、コードからすべてのスキーマを正確に推論したり、OpenAPI の意味的な正しさまで完全に検証したりはしません。付属のバリデーターも文字列ベースで、必須セクションの有無を見るだけです。したがって、導入価値が高いのは「信頼できる自動抽出」が欲しい場合ではなく、ガイド付きでドラフトを作るワークフローが欲しい場合です。

api-documenterスキルの使い方

api-documenterのインストール前提

このスキルは zhaono1/agent-playbook リポジトリ内の skills/api-documenter にあります: https://github.com/zhaono1/agent-playbook/tree/main/skills/api-documenter

スキル実行環境が GitHub からの直接インストールに対応しているなら、そのツールが想定するリモートスキルコレクションの手順で導入してください。対応していない場合は、リポジトリを clone して、ローカルのスキルディレクトリをエージェントツールに参照させます。よく使われる基本的な導入パターンは次のとおりです。

npx skills add https://github.com/zhaono1/agent-playbook --skill api-documenter

環境ごとの差異はあっても、重要なのはエージェントが skills/api-documenter/SKILL.md と関連ファイルを読めることです。

初回利用前に読むべきファイル

手早く api-documenter guide を把握したいなら、次の順で読むのがおすすめです。

1. 起動条件と期待されるドキュメントの形を確認する SKILL.md
2. 最低限の骨組みを見る references/openapi-template.yaml
3. どんなスターターファイルが生成されるか分かる scripts/generate_openapi.py
4. 内蔵チェックが実際に何を検証しているか理解するための scripts/validate_openapi.py
5. ごく小さな例を見る references/examples/openapi-example.yaml

この順番に意味があるのは、このリポジトリが長文の解説書というより、ワークフローの足場として使うと価値を発揮する構成だからです。

このスキルに必要な入力

api-documenter の精度が上がるのは、次のような具体的な情報を渡したときです。

• メソッドとパスを含むエンドポイント一覧
• リクエストパラメータと body の項目
• レスポンス例とステータスコード
• 認証方式
• Base URL や環境情報
• オブジェクト/スキーマ定義
• 命名規則とタグ

「この API をドキュメント化して」とだけ伝えると、汎用的な外枠で終わりがちです。エンドポイントごとの事実を渡せば、レビュー可能なドラフトにかなり近づきます。

あいまいな依頼を強いプロンプトに変える

弱いプロンプト:

Create OpenAPI docs for my API.

より強いプロンプト:

Use the api-documenter skill to draft an OpenAPI 3.0.3 spec for a REST API.

Base URL: https://api.example.com/v1
Auth: Bearer token in Authorization header

Endpoints:
- GET /users?page={number}&limit={number}
  - 200 returns array of User plus pagination metadata
- POST /users
  - body: name, email
  - 201 returns created User
  - 409 if email already exists
- GET /users/{id}
  - 200 returns User
  - 404 if missing

Schemas:
- User: id string, name string, email string, createdAt string(date-time)

Please include:
- summary, operationId, description, tags
- parameters and requestBody
- success and error responses
- components.schemas
- components.securitySchemes

後者が機能しやすいのは、業務ロジックを勝手に補わせずに、必須の OpenAPI セクションを埋めるための十分な構造をスキル側に与えられるからです。

何もない状態なら、まず付属ジェネレーターを使う

まだ仕様ファイルがないなら、先に骨組みを生成すると効率的です。

python scripts/generate_openapi.py --output openapi.yaml --name users --version 1.0.0 --base-url https://api.example.com

この方法が有効なのは、info、servers、paths、サンプルの schema ブロックを含む、構文上整理された出発点を作れるからです。その後でスキルを使い、プレースホルダーを実際のエンドポイントやスキーマ情報に置き換えていきます。

生成・編集した内容を検証する

編集後は、付属のバリデーターを実行します。

python scripts/validate_openapi.py --input openapi.yaml

このバリデーターは意図的に軽量です。openapi:、info:、servers:、paths:、components:、securitySchemes: といった必須見出しがファイル内にあるかを確認します。ドラフトの抜けを見つけるには便利ですが、仕様として完全に正しいことの証明にはなりません。

テクニカルライティング向けのapi-documenter運用フロー

api-documenter for Technical Writing として実務で回しやすい流れは次のとおりです。

1. エンジニア、コード、Postman コレクション、既存ドキュメントから一次情報を集める
2. テンプレートの骨組みを生成またはコピーする
3. 文章だけの説明ではなく、エンドポイント単位の事実を与えてスキルに依頼する
4. 命名の一貫性、レスポンスの網羅性、認証情報を見直す
5. バリデーターを実行する
6. 最終レビュー用に、仕様をエンジニアへ渡すか Swagger 系ツールで可視化する

この流れがテクニカルライターに向いているのは、構造面の手間をスキルが減らしつつ、編集判断そのものは人間側で保てるからです。

このスキルが最適化していそうな対象

リポジトリの内容を見る限り、このスキルは次の点に最適化されています。

• OpenAPI 3.0.3 の構造
• エンドポイント記述の抜け漏れを減らすこと
• 必須項目と推奨項目の区別が明確なこと
• 標準化とレビューに十分耐えるドキュメント

一方で、複数ファイルにまたがる高度な仕様、callbacks、webhooks、ポリモーフィズム、あるいは本格的な GraphQL スキーマ文書化のワークフローには、そこまで最適化されていません。

出力品質を上げる実践的なコツ

ちょっとした工夫でも api-documenter usage の質は大きく変わります。

• 「エラー対応あり」ではなく、正確なステータスコードを渡す
• 各エンドポイントに最低 1 つは具体的なレスポンス形を示す
• 項目が required か、nullable か、enum 的か、どの format かを明記する
• 認証方式は一度定義し、全体で一貫して参照するよう指示する
• チームがツール連携を始める前に、安定した operationId 命名を早めに決める

こうした情報が不足すると、見た目は整っていても運用上は曖昧な仕様になりやすい、という典型的な失敗を防げます。

api-documenterを自分向けに調整する際に見るべきパス

自分たちのワークフロー向けに調整したいなら、まず次のファイルから見るのが近道です。

• skills/api-documenter/SKILL.md
• skills/api-documenter/references/openapi-template.yaml
• skills/api-documenter/scripts/generate_openapi.py
• skills/api-documenter/scripts/validate_openapi.py

この並びで確認すれば、起動ルール、執筆テンプレート、初期生成、品質ゲートを一通りつかめます。

api-documenterスキル FAQ

api-documenterは初心者にも向いている？

はい。ただし、自分の API をすでに理解していることが前提です。このスキルは OpenAPI の書式面の負担を下げてくれますが、仕様全体を深く教えてくれるわけではありません。具体的なエンドポイントメモがあり、テンプレートやサンプルファイルと見比べながら進められるなら、初心者でも十分活用できます。

api-documenterは REST API 専用？

実務上は、ほぼそう考えてよいです。説明文には REST または GraphQL とありますが、リポジトリの実態は OpenAPI/Swagger のパターン、YAML サンプル、RESTful なパス例、エンドポイント中心のドキュメント構成に寄っています。主な作業が GraphQL のスキーマや resolver の文書化なら、最適な選択肢とは言いにくいでしょう。

AI に API ドキュメントを書かせるのと何が違う？

api-documenter の利点は、ワークフローに規律を持たせやすいことです。起動の手がかり、再利用できるテンプレート、生成スクリプト、検証スクリプトがそろっています。汎用プロンプトでもうまくいく場合はありますが、このスキルを使うとエージェントが目指すべき構造が明確になり、白紙状態で話が散るのを防ぎやすくなります。

api-documenterのインストールで完全なバリデーターも付く？

いいえ。内蔵スクリプトは、あくまで単純な完全性チェックであり、完全な OpenAPI パーサーや linter ではありません。厳密な検証が必要なら、最初のドラフト作成後に専用の OpenAPI ツールと組み合わせるのが現実的です。

api-documenterを使わないほうがいいのはどんなとき？

次のような場合は api-documenter を見送ったほうが合っています。

• 人手をほとんどかけずにソースコードから自動抽出したい
• API の中心が GraphQL で、GraphQL ネイティブなドキュメントが必要
• 高度な spec governance、bundling、linting、contract testing まで最初から必要
• OpenAPI の成果物ではなく、読み物として洗練された人間向け prose docs だけが欲しい

テクニカルライターでも、重いコーディングなしでapi-documenterを使える？

はい。むしろ強いユースケースのひとつは、テクニカルライターがエンドポイント情報を集め、スタータースクリプトを実行し、YAML を調整しながらエンジニアレビューに回す流れです。付属スクリプトを活用するのに、深い Python 知識は必須ではありません。

api-documenterスキルを改善するには

api-documenterに完全なエンドポイント情報を渡す

最も効果が大きい改善は、入力となる一次情報の質を上げることです。各エンドポイントについて、少なくとも次を用意してください。

• メソッドとパス
• 用途
• パラメータと body schema
• ステータスコードごとの response schema
• 認証方式
• エッジケースやエラーレスポンス

このスキルは、良い材料を構造化するのは得意ですが、信頼できる API 挙動を作り話で補うことはできません。

スキーマ記述のあいまいさを減らす

弱い API ドキュメントの多くは、フィールドの意味づけが不足しています。たとえば「user object」とだけ書くのではなく、次のように明示します。

• id: string, immutable
• email: string, unique
• createdAt: string, date-time
• status: enum active | suspended

こうすることで、api-documenter が生成する components は再利用しやすくなり、後から大きく書き直す必要も減ります。

書式ではなく網羅性を依頼する

改善指示としてより有効なのは、次のようなプロンプトです。

Review this OpenAPI draft with the api-documenter skill and identify missing:
- operationId values
- requestBody schemas
- error responses
- auth declarations
- shared component schemas
Then patch the spec.

この種の依頼は、単に「YAML をきれいにして」と頼むより、完成度の底上げにつながります。

主な失敗パターンを把握しておく

このスキルの出力で起こりやすい問題は次のとおりです。

• プレースホルダー説明が残ったまま
• components.securitySchemes が欠落している
• エラーレスポンスのカバレッジが薄い
• path operation に summary はあるが、schema の中身が乏しい
• 付属バリデーターは通るのに、実際には不完全なドラフト

あらかじめ失敗パターンを知っておくと、レビューがかなり速くなります。

テンプレートに自分たちのスタイル規約を重ねる

チーム内に命名規則や文書化ルールがあるなら、明示的に伝えるべきです。たとえば次のような点です。

• ドメインごとの tag 名
• operationId の動詞スタイル
• ページネーション形式
• エラー envelope の形
• 日付や enum の表記ルール

標準の api-documenter skill が与えてくれるのは構造です。実運用に耐える成果物にするのは、最終的にはチーム固有の規約です。

初稿のあとに絞って反復する

2 回目以降のプロンプトは、最初よりも対象を絞るほうが効果的です。

Using the api-documenter skill, revise this spec to normalize schema names, move repeated objects into components.schemas, and add 401/403/404 responses where applicable.

ゼロから再生成するより、このやり方のほうが、すでに役立っている構造を残したまま整合性だけを詰めやすくなります。

定常運用するならスクリプトを拡張する

api-documenter を継続的に使うなら、もっとも効果の大きい改善は補助スクリプトのカスタマイズです。たとえば次のような拡張が考えられます。

• generate_openapi.py を更新し、認証方式やエラー envelope をデフォルトで含める
• validate_openapi.py を --require で独自の必須見出しやトークンも検証できるよう広げる
• references/openapi-template.yaml の横に、自社向けのスターター仕様を置く

こうしておくと、汎用スターターではなく、チーム専用のドキュメント高速化基盤として使えるようになります。