`/api.json` が OpenAPI Specification として invaild な部分がある

Open zyoshoka opened this issue 1 year ago • 1 comments

💡 Summary

現在バックエンドの生成する OpenAPI 定義 /api.json は validate-api-json ワークフローによって validate され見かけ上通ってはいますが、ログを見ると 156 個の警告が出力されています（https://github.com/misskey-dev/misskey/actions/runs/7927440397/job/21643840936 の Validation を参照）。

これらの警告は、下記のコマンドで --extends=minimal オプションを取っ払うと153個のエラーと4個の警告に変わるため、対処すべきであると考えられます。

https://github.com/misskey-dev/misskey/blob/2744cbd310e7e1b7792fe455602f6e2cf376120d/.github/workflows/validate-api-json.yml#L47

警告の殆どを占めているのは次の2つです：

operation-operationId-unique (related: https://github.com/misskey-dev/misskey/issues/12640#issuecomment-1879515412 https://github.com/misskey-dev/misskey/pull/12969#discussion_r1451171724)
security-defined

（タイトルだけ見れば #10632 と同じですが内容が異なるので別で立てます）

🥰 Expected Behavior

pnpm --filter backend generate-api-json && redocly lint packages/backend/built/api.json でエラーが出ない

🤬 Actual Behavior

pnpm --filter backend generate-api-json && redocly lint packages/backend/built/api.json でエラーが出る（--extends=minimal 付きだとエラーは出ない）

📝 Steps to Reproduce

No response

💻 Frontend Environment

No response

🛰 Backend Environment (for server admin)

* Installation Method or Hosting Service:
* Misskey: 2023.3.0
* Node:
* PostgreSQL:
* Redis:
* OS and Architecture:

Do you want to address this bug yourself?

[ ] Yes, I will patch the bug myself and send a pull request

Mar 02 '24 07:03 zyoshoka

security-defined ルールのエラーは単に

security: [{
	bearerAuth: [],
}],

を追加すれば解消されるようです。

operation-operationId-unique ルールのエラーは allowGet が true なエンドポイントのみで生じているので get- / post- などの prefix をつければ直りそうです（それがベスト・プラクティスかどうかは分かりませんが…）

Mar 02 '24 07:03 zyoshoka