#openapi

この記事を読んでまず思ったのは、MCPを「新しい世界の入口」みたいに扱うと少し危ない、ということだった。実際にはかなりの場面で、MCP server は既存APIの薄い wrapper に近い。そう考えると、壊れる場所はMCPの見た目より、下にあるAPIの契約だよな、と腑に落ちた。 特に引っかかったのは、MCP側が静かに見えてしまう点だ。外から見ると tool の形は変わっていないのに、APIで必須パラメータが増えたり、enum の値が減ったりすると、あとから agent の挙動が妙になる。こういう壊れ方は、普通のAPI連携よりも発見が遅れそうで厄介だと思う。エラーとして派手に落ちず、ただ「なんか変」になるのが一番面倒だから。 一方で、この記事はMCPを過大評価しないところがいい。OpenAPI を持って CI で diff を見て、breaking change かどうかを先に判定してから MCP wrapper を更新する、という現実的な話に落としている。新しい仕組みを入れると、ついその層だけ整えたくなるけれど、順番は逆なんだという指摘はかなり実務的だと思う。 読み終えて残ったのは

いちばん気になったのは、「APIの正しさ」と「AIにとって使いやすいこと」が、同じではないとかなりはっきり切り分けていたところです。人間向けのAPI設計だと、path、query、header、body に分かれているのは自然です。でもAIに tool として見せるときは、その分かれ方がむしろ邪魔になる。この記事はそこを雑に一つへ潰すのではなく、役割ごとにどう持ち込むかを丁寧に考えていて、そこは素直にうれしかったです。 特に引っかかったのは、authentication header を tool input に入れないという話です。これは当たり前のようで、実際にはかなり大事だと思います。`Authorization` をモデルに見せると、APIの操作を説明するはずの schema に秘密情報の話が混ざる。そうなると設計が一気に汚れるし、責任の境目もぼやける。逆に、`Idempotency-Key` みたいなものは場合によってはサーバ側で生成してしまう、という判断もいい。AIに「何でも入力させる」のではなく、面倒なものは隠してよい、という姿勢がちゃんとあるのが好印象でした。 もう一つ面

OpenAPIは、APIの「設計図」みたいなもの Spring Bootでは `springdoc-openapi` を使うと、コードからOpenAPI定義を出せる ただし、手で保存する方法は面倒で、CIには向かない 記事の核心は「アプリを起動した状態で、MavenプラグインにOpenAPIを取りに行かせる」こと そのために `openapi` 用のSpring profile を分けているのがうまい CIでAPI仕様を自動生成できると、フロントエンド連携や契約テストがかなり楽になる この記事は、Spring Bootアプリから OpenAPI 仕様を自動生成し、それを CI pipeline に自然に組み込む方法を紹介しています。 まず前提として、OpenAPIはAPIの仕様を機械が読める形で表したものです。人間にとっては「このAPIはGETで、こういう入力を受けて、こういう出力を返す」と読めるし、ツールにとっては「クライアントコードを作るための材料」になります。 ここが大事で、OpenAPIはただのドキュメントではありません。 実際には次のような用途でかなり役に立ちます。