エクセルを使わないでマークダウンでapiのドキュメントを作成する

apiのドキュメントを作成する際にエクセルを使って見栄えの良い(?)ドキュメントを作成することはよくあります。

ですが、以下のことが起きたりします。

• キレイな表を作成することに力を入れてしまう
• 更新されない
• xxx_v1とかxxx_v2というファイルが増える

これをできるだけ起こさないように取り組んでいる方法を紹介します。

自分なりの方法

エクセルではなく、githubのreadmeを使ってapiのドキュメントを管理するようにしました。

マークダウンでドキュメントを作成するライブラリ（blue printやaglio、swagger）を使っても良いのですが、使うために導入が面倒です。

ある程度人にわかるように書けて、更新履歴がわかれば良いです。

どのように作成するかと言うと、↓のように作成します。

（swaggerを真似て、必要なところだけ書き方を模倣している形です）

# タスクを追加するapi

タスクを追加するapiです。

## /api/task

method: post

request_params
name:
    type: str
    valid:
        not blank

response
result:
    type: bool
message:
    type: str

この方法のメリットとしては

• ドキュメントを作成するのに疲弊しない
• 管理が楽になる（xxx_v1とかxxx_v2というファイルが増えない）

デメリットとしては

• ドキュメントのフォーマットが安定しない
  • 一度フォーマットが決まれば、コピペである程度回避できるが
• 表を作成しようとすると|で作ることになるので面倒