website·Indexed 31 days ago
https://wirespec.ioA contract-first interface design tool that automates and standardizes the process of building and testing interfaces. Wirespec provides a compiler to turn .ws source files into target-language source code via emitters for Java, Kotlin, TypeScript, Avro, and OpenAPI (v2 and v3). It includes plugins for Gradle, Maven, and NPM, as well as IDE support for IntelliJ IDEA and VS Code.
Wirespec provides built-in integrations for several major frameworks and libraries to support enterprise development, data serialization, and testing. Supported integrations include:
Wirespec provides an IR extension that automatically adds kotlinx.serialization annotations to generated Kotlin models during compilation. This removes the need to manually edit or wrap generated code.
Behavior:
@Serializable and @SerialName("<wirespec name>").union and enum types are annotated with @Serializable.Path, Request, and Response types nested inside an endpoint) are ignored.// Example of generated output for a 'Todo' type
@kotlinx.serialization.Serializable
@kotlinx.serialization.SerialName("Todo")
data class Todo(
val id: TodoId,
val name: String,
)The IR pipeline runs inside emitters (e.g., JavaIrEmitter, KotlinIrEmitter, PythonIrEmitter, RustIrEmitter, ScalaIrEmitter, TypeScriptIrEmitter) and sits between the parser's AST and the final source code output. It consists of three stages:
The Wirespec TypeScript emitter generates a core Wirespec namespace containing the fundamental types and interfaces required for serialization, transportation, and API definition. Key components include:
BodySerialization, PathSerialization, and ParamSerialization to handle the conversion between high-level types and raw formats (Uint8Array or string).Transportation interface defines the transport method which sends a RawRequest and returns a Promise<RawResponse>.Api type defines a service endpoint including its method (GET, POST, etc.), path, and the client/server logic for transforming requests and responses.GeneratorField types (e.g., GeneratorFieldInteger32, GeneratorFieldEnum, GeneratorFieldShape) used by the Generator interface to produce mock or test data.export namespace Wirespec {
export type Method = "GET" | "PUT" | "POST" | "DELETE" | "OPTIONS" | "HEAD" | "PATCH" | "TRACE"
export interface Request<T> {
path: Path;
method: Method;
queries: Queries;
headers: {};
body: T;
}
export interface Response<T> {
status: number;
headers: {};
body: T;
}
export interface Transportation {
transport(request: RawRequest): Promise<RawResponse>;
}
export type RawRequest = {
"method": string,
"path": string[],
"queries": Record<string, string predation>,
"headers": Record<string, string predation>,
"body": Uint8Array | undefined,
}
export type RawResponse = {
"statusCode": number,
"headers": Record<string, string predation>,
"body": Uint8Array | undefined,
}
// ... other serialization and generator interfaces
}