Swaggerとは？〜openAPI仕様書の作り方〜

Swaggerの概要をまとめてみた。 - Qiita
Swagger ツール群

• Swagger Spec ：REST APIに対して Swagger の仕様に準じたドキュメント
• Swagger Editer ：Swagger Spec の設計書を記載するためのエディタ
• Swagger UI Swagger ：Spec で記載された設計からドキュメントをHTML形式で自動生成するツール
• Swagger Codegen ：Swagger Spec で記載された設計からAPIのスタブを自動生成

API仕様書作成の流れ（Swagger Editerで作成する場合）

1. SwaggerEditerを開く
2. 仕様書を記述する
3. 保存する（YAMLまたはJSON形式）

API仕様書の書き方

参考

• SwaggerでAPI設計書作成
  • 仕様書の書き方の概要を説明してくれている記事
• API仕様書のサンプル（NotePM API） - NotePM
  • 仕様書のサンプル。
  • 目次があって全体像が掴みやすい。
• ［API］ API仕様書の書き方 - Qiita
  • APIの一覧（機能一覧）
  • APIごとの詳細
    • 概要
    • アクセス先URI
    • 入力するJSON形式データの内容
    • 返却されるJSON形式データの内容
      • 処理結果ステータスの内容
• 岐阜県リアルタイムデータ提供プラットフォーム WebAPI仕様書
  • 実際のAPI仕様書として参考になる

Zalando RESTful API and Event Guidelines