Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
myConsciousness opened this issue Feb 24, 2023 · 4 comments

Comments

@myConsciousness
Copy link

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

スクリーンショット 2023-02-24 21 36 09

@myConsciousness
Copy link
Author

追記:

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

スクリーンショット 2023-02-26 8 58 06

@sei0o
Copy link
Contributor

sei0o commented Feb 28, 2023

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

@sei0o
Copy link
Contributor

sei0o commented Feb 28, 2023

参考:現時点で 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
Copy link
Author

myConsciousness commented Mar 3, 2023

#222 と関連。

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants