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

Đang mở
  • Có gì không ổn?
#434 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
csharp, openapi
Lĩnh vực
backend-api-design

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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).
Ngôn ngữ chính
C#
Star
1
Fork
0
Merge trung bình
2 giờ 2 phút
Pull request đã merge (30 ngày)
98

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của nevridge/TaskFlow

Tất cả issue của nevridge/TaskFlow

Issue tương tự

Thêm issue về C#

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.