spike: generate the assistant's API client from the OpenAPI document

オープン
  • 何か問題がありますか？
#434 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
35/100
issue の種類
機能追加
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
csharp, openapi
領域
backend-api-design

調査の方向性

Start by reading assistant/src/TaskFlow.Mcp/Api/ApiModels.cs and TaskFlowApiClient.cs to list the operations and DTOs in use; compare them with the OpenAPI document and the generated web client under TaskFlow.Web/src/api/client/**. Prototype the task endpoints with a candidate option, then measure source size, plugin publish size, build needs, CI changes, and test impact. Finish with the comparison table, prototype test results, recommendation, and any required follow-up issues.

索引モデルが issue の本文から書いたものです。

説明

tech-debt

Found while reviewing the assistant-builder agent for #400 (piece 8). The assistant's HTTP client and its DTOs are written by hand to mirror TaskFlow.Api, while the web client is generated from the API's OpenAPI document. This spike asks whether the assistant's client should be generated too.

What I found

  • assistant/src/TaskFlow.Mcp/Api/ holds 341 lines: ApiModels.cs (101), TaskFlowApiClient.cs (221) and TaskFlowApiException.cs (19). None of it is generated.
  • The web client (TaskFlow.Web/src/api/client/**) is generated from /openapi/v1.json with openapi-ts and committed. The backend builder regenerates it when the API surface changes, so a stale web client is caught at the source.
  • Nothing equivalent protects the assistant. When the API changes a DTO or endpoint, the assistant mirror is updated by hand, by the assistant builder, from the brief. A change nobody remembers shows up only as a runtime error from a tool or as a failing test, if one exists.
  • assistant/ is a separate solution (its own .sln, Directory.Build.props and .editorconfig) that ships as a plugin binary, so any option has to respect that boundary and the published size.

Scope

  1. Read the client and models and list which API operations and DTOs the assistant actually uses (a subset of the API).
  2. Compare these options on a prototype of one endpoint family (the task endpoints are a good candidate):
    • Generate a C# client from the OpenAPI document (Kiota, NSwag, openapi-generator or the Microsoft OpenAPI client tooling). Check generated size, how it fits ToolGuard and TaskFlowApiException, and how little of it the assistant needs.
    • Reference the API's DTOs directly (a shared project or a project reference). Check what it does to the separate solution and the plugin publish.
    • Keep the hand-written client and add a contract test that compares it to the OpenAPI document and fails on drift.
    • Keep things as they are.
  3. For each option, measure or estimate: lines of source kept in the repo, publish size of the plugin binary, build-time needs (a running API or a committed spec file), CI changes, and test impact. The assistant has about 480 tests.
  4. Say how each option changes the pipeline from #400: who regenerates the assistant client, and in which stage, if it is generated.
  5. Note how this interacts with #428, the enum casing spike. If responses use PascalCase enum names, a generated client's enum handling depends on that decision.
  6. Recommend one option.

Acceptance criteria

  1. A comparison table is posted on this issue, with the measurements from scope item 3 for at least three options.
  2. The prototype for the leading option builds and the existing task tool tests still pass against it, or the issue says why it was dropped.
  3. A recommendation is recorded. If generation is recommended, follow-up issues are opened for the migration and for the pipeline change; if not, the issue says what keeps the mirror honest (for example the contract test).

Out of scope

  • Migrating the assistant to the generated client. This issue produces a decision and follow-up issues.
  • The web client, which is already generated.
  • The timezone offset representation (a separate spike).
主要言語
C#
スター
1
フォーク
0
平均マージ
2時間 2分
マージ済み PR（30日）
98

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

nevridge/TaskFlow のほかの issue

nevridge/TaskFlow の issue をすべて見る

似ている issue

C# の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。