エンドポイントページのパラメータには説明が必要か

[myConsciousness]

Misskey APIのエンドポイントページにはパラメータの型情報などはありますが、各パラメータの説明がないので特定のパラメータを渡した場合に具体的にどう機能するのかがわかりません。開発者の理解を助けるためにもパラメータの説明が必要なのではないかと思います。

[myConsciousness]

追記:

いろいろとエンドポイントを見ていると、パラメータの説明が付与されているエンドポイントも存在する。

[sei0o]

各エンドポイントについて、仕様を示した .json5 ファイルが src/docs/api/endpoints 以下にあります。それぞれのパラメータのフィールドに description という項目を追加して記述すると、Misskey Hubのページにも表示されます（/notesの例）。

[sei0o]

参考：現時点で description の追加が完了していないディレクトリの一覧です（抜け漏れはあると思います）。

src/docs/api/endpoints
├── admin/
├── antennas/
├── ap/
├── app/
├── channels/
├── charts/
├── endpoint.json5
├── endpoints.json5
├── fetch-rss.json5
├── gallery/
├── messaging/
├── meta.json5
├── my
│   └── apps.json5
├── promo
│   └── read.json5
├── request-reset-password.json5
├── reset-password.json5
├── sw/
├── test.json5
├── users
│   ├── clips.json5
│   ├── followers.json5
│   ├── following.json5
│   ├── gallery
│   │   └── posts.json5
│   ├── lists
│   │   ├── create.json5
│   │   ├── delete.json5
│   │   ├── list.json5
│   │   ├── pull.json5
│   │   ├── push.json5
│   │   ├── show.json5
│   │   └── update.json5
│   ├── notes.json5
│   ├── relation.json5
└── users.json5

[myConsciousness]

#222 と関連。

こうしたjson5ファイルで使用できる description といったフィールドは全て明文化されるべき。そうでなければコントリビューターの不要な調査が必要になる。