2025年9月7日日曜日

Web APIの仕様書には、OpenAPI（旧Swagger）、Postman、Markdownなど複数の形式があります。

 Web APIの仕様書には、OpenAPI（旧Swagger）、Postman、Markdownなど複数の形式があります。OpenAPIは業界標準で、YAMLやJSONで記述し、Swagger UIで視覚化も可能。Postmanはコレクション機能でAPIをテスト・整理しやすく、ドキュメント生成も対応。Markdownはシンプルな構造で記述しやすく、専用ツールでモックやサーバーを生成可能。いずれもAPI仕様の明確化やチーム共有、保守性向上に役立ちます。用途に応じて選択するのが効果的です。

🔷 OpenAPI（Swagger）仕様の例

  • GitHub APIのOpenAPI仕様（Swagger UI）
    https://docs.github.com/en/rest
    → GitHubのREST APIがOpenAPI仕様でドキュメント化され、操作しながら確認可能。

  • Petstoreのデモ（Swagger公式サンプル）
    https://petstore.swagger.io/
    → OpenAPI 3.0ベースの代表的なデモ。仕様定義からUI表示まで確認可能。

  • OpenAPI仕様のYAML例
    https://swagger.io/specification/
    → OpenAPI 3.0の構造や記法を学ぶのに最適な公式ドキュメント。

🟠 Postman コレクションの例

🔶 Markdown形式のAPIドキュメント例

  • GitHub Actions API ドキュメント（Markdownベース）
    https://docs.github.com/en/actions
    → GitHubはMarkdownで整備された静的ドキュメントとしてAPIを管理。

  • FastAPIのドキュメント自動生成例（Markdown起点）
    https://fastapi.tiangolo.com/
    → PythonのFastAPIではMarkdownコメントからドキュメントを生成可能。

  • ReDoc によるMarkdownドキュメントのレンダリング例
    https://redocly.github.io/redoc/
    → MarkdownやOpenAPIを視覚的に変換するReDocのデモ。


投稿者