APIの設計書の例ってありませんか？

Question

既存のAPIのソースからドキュメントを起こさないといけないのですが、ドキュメントの作成の参考資料を探しています。
Googleで「API 設計書」と検索すると、API仕様書の作り方が多く出てきてしまいます。
こちらなどはSwaggerを使っていますが、これは設計書というより外部からAPIを使うための仕様書のように見えます。
https://www.indetail.co.jp/blog/161220/
これではお客様に提出できませんし、後続のメンバーに共有できません。リクエストやレスポンスやMethodだけでなく、内部の処理フローも書かなければなりません。

画面のレイアウトや画面遷移は、IPAのドキュメントに参考になりそうなものがありました。
https://www.ipa.go.jp/sec/softwareengineering/reports/20080710_3.html
しかし、APIに関して似たような物はありません。

ドキュメントの目的は、お客様や後続のメンバーへ処理内容を伝える事です。
試しに作ってみたら、バッチの設計書に近い物になってしまいました。

APIの設計書のサンプルや参考資料など、ご存じでしたら教えて頂きたいです。

Answer 1

必要なのは API の「内部設計」ですよね。
普通に API 仕様書といった場合はインターフェース（呼び出し方法、返却データのフォーマット）と呼び出しにおける注意事項が記載されているもののことを指すことが多いので、確かに内部ロジックまで書いた仕様書としては出てこないと思います。

この場合、できればインターフェース仕様書と処理設計書の二つに分けた上で、処理設計書は通常のプログラムのようなイメージで記述することになるでしょう（つまりはバッチの設計書に近いものになる、で正しい）。

あとは、インターフェース仕様書は「すべての発生しうる結果を書く」必要があるくらいでしょうか。ドキュメントにない挙動をしたら、利用者が困りますから。

Comments

[currysita]

なるほど、一つのドキュメントで考えるから解りづらいんですね。バッチの設計書のようなものだと、なんだか違和感があるな…と思っていたのですが、すっきりしました。
インターフェース仕様書と内部設計書という形で分けてみようと思います。ありがとうございました。

Answer 2

確かにあまりその手のサンプルは見かけませんね。
今sketchのプラグインを作っていますが、ここの公式サイトのAPI仕様書は見やすく出来ていると思いますよ。
他にはSwiftの公式仕様書ですかね？すべて英語で書かれていますが、結構しっかり書かれているので書き方としてはおススメです。

Comments

[currysita]

sketchの仕様書、ソースのサンプル付きなんですね。これは見やすい。それに何だかおしゃれ。
時間かけて読んでみようと思います。ありがとうございます。

[stdio]

もともとデザイナ向けのアプリケーションのサイトですからね。オシャレなのは当然です。
しかし、個人的にはもう少し情報が欲しいです。書いてない事多過ぎです。