Unified Interface Modelを最小限で定義 - #6
Merged
Merged
Conversation
Implements issue/004: src/core/model.ts, a protocol-agnostic
representation of an API surface (service, operations with
method/path/parameters/requestBody/responses, and a named schemas
map for reused/ref'd types). UI and later parsers depend only on
this shape, never on OpenAPI's own types.
$ref targets are kept as named entries in schemas and pointed to via
{ type: "ref", name } rather than inlined everywhere, mirroring
OpenAPI's components/schemas, so the UI can show/reuse named types.
issue/004 documents the design rationale and a worked OpenAPI ->
model mapping example covering every element the task called for
(method, path, description, parameters, request body, response,
schema, enum, examples, deprecated). Verified: npm run build, npm
test, npm run format:check.
Validate the model against every protocol issue #1 lists (gRPC, GraphQL, AsyncAPI/Kafka, standalone JSON Schema) in docs/unified-interface-model.md before locking in field names — merging InterfaceOperation with OpenAPI-only method/path fields would have meant a guaranteed breaking rename the moment a second protocol parser landed. Renames UnifiedApiModel -> UnifiedInterfaceModel and drops the "Api" prefix throughout (InterfaceOperation, InterfaceParameter, etc.). Replaces the required method/path pair with action/target, which holds up across all four protocols examined (e.g. AsyncAPI: action "PUBLISH", target the channel name). InterfaceResponse.status becomes optional since gRPC/GraphQL/AsyncAPI don't have OpenAPI's per-status-code response concept. Parameter "in" locations and the shape of requestBody/responses stay REST-shaped for now — those get extended when an actual second parser is implemented, not guessed at here. Propagates the renamed terminology through README and the other issue/*.md files that mentioned "Unified API Model". Verified: npm run build, npm test, npm run format:check.
Other agents implement against this doc and humans read it to
understand the model; narrating the validation process ("検証した",
"確認できたため") gets in the way of that. State the mapping as
settled fact instead.
ningenMe
commented
Aug 16, 2026
| @@ -0,0 +1,54 @@ | |||
| // Protocol-to-model mapping is validated in docs/unified-interface-model.md before changing this shape. | |||
| export interface UnifiedInterfaceModel { | |||
| service: string; | |||
ningenMe
commented
Aug 16, 2026
| deprecated?: boolean; | ||
| parameters: InterfaceParameter[]; | ||
| requestBody?: InterfaceRequestBody; | ||
| responses: InterfaceResponse[]; |
Owner
Author
There was a problem hiding this comment.
summaryとか最初不要なような、yagniにしよう。もっとスリムに。
Review feedback: designing a recursive schema union, named-ref resolution, and a cross-protocol action/target generalization before any parser or UI exists is over-engineering. None of it has been exercised against real code yet, so it's likely to be wrong in ways that only show up once 005 (parser) and 008 (detail view) actually need these fields. Reverts to a minimal UnifiedInterfaceModel/InterfaceOperation with just service/id/method/path/description/deprecated. Parameters, request body, response, schema, enum, and examples are deliberately left undefined until the tasks that need them (005, 008, ...) grow the type against real data. Drops docs/unified-interface-model.md, which validated the now-reverted action/target design; it can be rewritten once a second protocol parser is actually underway.
Nothing parses into it or reads it yet, and its meaning wasn't settled (service name? source name? application name?). Grouping a parsed model with the sources.yaml entry it came from belongs to 006-implement-source-registration, not baked into the model itself.
Rolling everything about the earlier design back to method/path left issue/004's decision log arguing for action/target while the code used method/path — a naming choice that costs nothing extra and was already validated across OpenAPI/gRPC/GraphQL/AsyncAPI shouldn't have been swept up in the "don't over-build" rollback along with the actually-complex parts (schema unions, ref resolution).
With only one field (operations), the wrapper was identical to InterfaceOperation[] in practice — no parser or site-generation code exists yet to say whether it needs to be anything more than that. Bring the wrapper back once a second top-level field (e.g. schemas) is actually needed.
README doesn't need to mirror core/model.ts's exact current shape — that's what issue/004's decision log is for. Point there instead of restating field names that just went through three rounds of churn, and describe the directory by what's actually in it (InterfaceOperation) rather than a wrapper type that no longer exists.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
src/core/model.tsに最小限の型を追加UnifiedInterfaceModelラッパー(service含む)まで作っていたが、parserもUIもまだ無い段階でそこまでやるのは過剰と判断し、使う側が無いものは全部削除InterfaceOperation { id, action, target, description?, deprecated? }のみmethod/pathではなくaction/targetという命名だけは残した。単なる命名でOpenAPI以外のprotocol(gRPC/GraphQL/AsyncAPI)でも「動詞的な軸」「対象の軸」に分解できることは検証済みのためUnifiedInterfaceModelラッパー(schemasなど)は型を定義せず、005(parser実装)・008(詳細画面実装)で実データを見ながら育てるTest plan
npm run build(型チェック)npm testnpm run format:check