Skip to content

refactor: adopt OpenAPI vocabulary across the networkmock API #75

Description

@MaxMichel2

Part of #72

Depends on #1, #2.

Summary

Rename the public API surface to use OpenAPI's own vocabulary wherever a type models something OpenAPI describes, while deliberately keeping DevView-specific names for types that model DevView's own runtime mocking behaviour (which OpenAPI has no concept of). Doing this now is free — the API already breaks in 0.2.0 — whereas doing it in a later release would be a second breaking change.

Rule

A type takes the OpenAPI term when it models something the spec describes (a document, an operation, a server). It keeps its DevView name when it models DevView's own mocking behaviour — matching a request, holding a served response, persisting on/off state. Those concepts have no OpenAPI counterpart, and renaming them would incorrectly imply an equivalence.

Rename table

Current New Rationale
ApiGroupConfig ApiSpec one OpenAPI document per group
EnvironmentConfig (deleted in #2)ApiSpec.servers: List<String> OpenAPI servers[].url
EndpointConfig Operation OpenAPI Operation Object
EndpointOverride, EndpointDefinition, effectiveEndpoints (deleted in #2) existed only to vary endpoints per environment
EndpointKey(groupId, environmentId, endpointId) OperationKey(specId, operationId) operationId is the exact field name integrators type in their spec
EndpointDescriptor OperationDescriptor config-side snapshot of an operation + its responses
EndpointConfig.queryParams Operation.queryParameters matches OpenAPI parameters with in: query
EndpointMockState OperationMockState keyed on an operation; keeps the word "Mock" — it is DevView runtime state, not an OpenAPI concept
MockConfiguration.apiGroups MockConfiguration.specs field rename to match ApiSpec
GroupEnvironmentUiModel ApiSpecUiModel UI tabs become one per spec (see #7)
EndpointUiModel OperationUiModel
NetworkMock(configPath: String) NetworkMock(specPaths: List<String>) one file per group now ⇒ integrators pass a list
MockResponse kept as-is a runtime mock artifact: it exists only when a mock is actually served on an intercepted request. Sourced from an OpenAPI Example at config time, but it is not one — an OpenAPI Example is documentation; a MockResponse is a served response. A live (unmocked) request produces neither a MockResponse nor anything OpenAPI-shaped.
MockMatch kept as-is, .endpointId.operationId matching an incoming request to a configured operation is DevView's own concept; OpenAPI has no term for it
NetworkMockState, MockConfigRepository, MockStateRepository kept as-is DevView plumbing, not OpenAPI concepts

Do not rename MockResponse → e.g. ResponseExample or MockMatchOperationMatch — this was explicitly considered and rejected (see "Deliberately skipped" section of the original audit/plan). If you find yourself wanting to make that rename while doing this issue, stop and re-read the rule above; the two concepts are genuinely different.

Why do this now, in its own PR

Acceptance criteria

  • Every rename in the table above is applied consistently across devview-networkmock-core, devview-networkmock, and devview-networkmock-ktor.
  • MockResponse and MockMatch are explicitly not renamed — call this out in the PR description so reviewers know it's deliberate, not an oversight.
  • KDoc is updated everywhere the old names appear (grep for EndpointConfig, ApiGroupConfig, EndpointKey, GroupEnvironmentUiModel, EndpointUiModel, EndpointDescriptor across all three modules' commonMain).
  • api/api.txt regenerated for all three affected modules.
  • konsist architecture tests still pass (dependency rules are about module boundaries, not type names, but double check nothing hardcodes an old name).

Files likely touched

Every file under the three networkmock modules that references any renamed type — this is a wide, mechanical diff. Suggested approach: do the rename with IDE refactoring tools (rename symbol) rather than manual find-replace, to catch KDoc [Link] references automatically where possible.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions