Service schema typegen ideas

Definitions

Mocked service: application to which Zimic mocks are targeted
Client application: application that consumes the mocked service and where Zimic mocks are applied

Initial ideas

Alternative 1: Types inferred from source code

Assessment: promising, not feasible directly.

A utility package could be installed in a mocked service, allowing automatic schema type generation by a CLI. The generated types are exported to an intermediate package that must be imported by client apps.

Workflow:
1. [mocked service] Install the utility package.
2. [mocked service] Use helpers to "mark" endpoints and extract type schema? Infer type schema from framework utilities?
3. Idea 1: declare the schema manually and provide utilities to validate if the endpoints are following it (promising)
4. Idea 2: derive the schema from an OpenAPI specification and provide utilities to validate if the endpoints are following it
5. [mocked service] Generate type schema of all of the endpoints using a CLI.
6. [intermediate package] Commit and upload the generated types to a shared package.
7. [client app] Install the intermediate package and import the generated types when creating interceptors.
Pros:
- Type schema is derived directly from the source code in the mocked service.
- A static type check could be integrated to CI environments to verify if the mocks are using valid types.
Cons:
- Dependent of which framework or code patterns where used in the mocked service.
- Adapters might be necessary.
- Code markers might be necessary.
- Not easily portable to mocked services using programming languages different from TypeScript.
- Requires an intermediate types package.
- Does not work if the client app developer does not have access to the source code of the mocked service (e.g. GitHub API could not be used)

Alternative 2: Types inferred from real requests

Assessment: not promising, requires manual intervention and is error prone.

A utility package could be installed in client apps, allowing automatic schema type generation by inferring the types from real requests.

Workflow:
1. [tested service] Install the utility package.
2. [tested service] The client app makes requests to the mocked service, without any mocks applied. The requests reach the real service,
3. [tested service] The utility package tracks the sent requests and generates the type schema.
4. [tested service] The generated schema can be used when creating interceptors.
Pros:
- Type schema is derived directly from the behavior of the mocked service.
- Independent of frameworks used in the mocked service.
- Independent of programming languages used in the mocked service.
- Does not use intermediate packages.
- Does not require changes to the source code of the mocked service (e.g. GitHub API could be used).
Cons:
- Relies that the client app developer runs the program reaching the real mocked service at least once for each possible request and response types.
- Type schema cannot be easily generated and validated as part of a CI workflow.

Alternative 3: Types derived from endpoint specification

Assessment: most promising, will be implemented into Zimic.

Having access to the mocked service endpoint specification, Zimic could automatically generate the type schemas. The endpoint specification could follow the standard OpenAPI.

Workflow:
1. [mocked service] Provide a path to get the OpenAPI specification of the service endpoints.
2. [tested service] Fetch the OpenAPI specification and generate the type schema, by CLI or script.
3. [tested service] The generated schema can be used when creating interceptors.
Pros:
- Type schema is derived directly from the expected behavior of the mocked service.
- A static type check could be integrated to CI environments to verify if the mocks are using valid types.
- Independent of frameworks used in the mocked service.
- Independent of programming languages used in the mocked service.
- Does not use intermediate packages.
- Does not require changes to the source code of the mocked service (e.g. GitHub API could be used).
- There are already utility types that convert OpenAPI to TypeScript types (see https://github.com/drwpow/openapi-typescript and https://github.com/anymaniax/orval).
Cons:
- Requires the mocked service to provide an OpenAPi specification.
- Although OpenAPI is comprehensive, there are no guarantees that the code of the mocked service is following the specification, as it is not statically enforced. However, other programming languages do not have the TypeScript's rich ability to derive types, so this might not be a big problem.
- HTTP-only if OpenAPI is used.

Extra: OpenAPI auto-generation

There could be ways to infer the OpenAPI specification from the source code of the mocked service. By doing this, alternatives 1 and 3 are combined:

If the mocked service already has an OpenAPI specification, it could be used by client apps to generate the type schema for mocks.
If the mocked service does not have an OpenAPI specification, it could be generated from the source code and provided in one of the endpoints or file, which could be accessed by client apps to generate the type schema for mocks.

See:

zimicjs / zimic