web API仕様書の書き方

Question

Web APIの仕様書は書いたことがなくて、困っています、
やりたいことは、相手が送るデータを受け取る側として、api仕様書に書くべき必須項目はなにかわからないです。
今の所、思いついたのは下記の3点です、他に何をどこまで、まとめればいいですか？

1,パラメータは：下記:
jsonフオーマット(テーブルの項目)

2,Base URL:
https://example.com

3,Endpoint: /user
https://example.com/user

Answer 1

API BluePrintなどもよいかと思います。

【API Blueprintの使い方】Web APIの仕様書を書く・読む・実行する

個人的には、必須項目はパラメータとその値の型、必須か否か、それとAPIの返り値は必須かと思います。
実行可能なドキュメントであればなお良いかと。

Comments

[hyskyo]

API仕様書はTakeoAsaiさんとmomon-gaさんがご指摘のAPI BluePrintやswaggerなどを使って相手に提出するできるんですね！！勉強になりました。普通はExcelなどで文章なぢ書くイメージが強かったので、新鮮で勉強になりました。

[hyskyo]

ありがとうございます。

Answer 2

OpenAPI(swagger)なんかどうでしょう。

swagger入門の記事見て、採用検討してみてはいかがでしょう。

Comments

[hyskyo]

勉強になりました。
ありがとうございます
。

Answer 3

twitterのapiのリファレンス なんかが参考になりませんか。

Comments

[hyskyo]

ありがとうございます

Answer 4

同じく作成していて、こういった検索ワードをするとGMOとか社内システム系の仕様書がいくつかヒットしました
https://www.google.com/search?q=api%E4%BB%95%E6%A7%98%E6%9B%B8+header+token&oq=api%E4%BB%95%E6%A7%98%E6%9B%B8+header+token&aqs=chrome..69i57.15155j1j7&sourceid=chrome&ie=UTF-8

あと書き方の中で一番参考になったQiitaも貼っときます
https://qiita.com/sunstripe2011/items/9230396febfab2eae2c2

Answer 5

私も、 API のドキュメント作成方法を模索、評価中です。

• apipie で api リファレンスドキュメントの作成練習をしてみた

https://qiita.com/katoy/items/d10cc97ec72bf2e36d96

• API のドキュメントツール swagger のサンプです。

https://github.com/katoy/swagger-demo

上のリンク先には、ドキュメント画面のスクリーンショットもあります。