### Installation Source: https://github.com/flock-community/wirespec/blob/master/src/plugin/npm/README.md Install wirespec globally or as a dev dependency. ```bash # Install as a dev dependency npm install --save-dev wirespec # Or install globally npm install -g wirespec ``` -------------------------------- ### Install dependencies Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/README.md Command to install project dependencies using npm. ```bash npm install ``` -------------------------------- ### wirespec(...) factory in Java Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/integration/integration-wiremock.mdx Example of using the wirespec(...) factory in Java to start a stub. ```java wirespec(new GetTodos.Handler.Handlers()) ``` -------------------------------- ### Generate Kotlin code from Wirespec definition Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/getting-started/getting-started.mdx Compiles a Wirespec definition to Kotlin, generating DTOs and endpoint structures. ```bash wirespec compile --input . --language kotlin ``` -------------------------------- ### wirespec(...) factory in Kotlin Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/integration/integration-wiremock.mdx Example of using the wirespec(...) factory in Kotlin to start a stub. ```kotlin wirespec(GetTodos.Handler) ``` -------------------------------- ### Convert Command Example Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/plugins/plugins-cli.md An example of how to use the 'convert' command to convert OpenAPI V2 to another format. ```shell wirespec convert OpenAPIV2 "$(cat types/openapi/petstore.json)" ``` -------------------------------- ### Wirespec Maven Plugin Configuration Source: https://github.com/flock-community/wirespec/blob/master/examples/maven-spring-convert/README.md This XML configuration shows how to set up the wirespec-maven-plugin to convert OpenAPI v2 and v3 specifications into Kotlin and Java code. It includes examples for different package names and shared settings. ```xml community.flock.wirespec.plugin.maven wirespec-maven-plugin 0.0.0-SNAPSHOT kotlin-v2 convert ${project.basedir}/src/main/openapi/petstorev2.json ${project.build.directory}/generated-sources community.flock.wirespec.generated.kotlin.v2 OpenAPIV2 Kotlin true kotlin-v3 convert ${project.basedir}/src/main/openapi/petstorev3.json ${project.build.directory}/generated-sources community.flock.wirespec.generated.kotlin.v3 OpenAPIV3 Kotlin false java-v2 convert ${project.basedir}/src/main/openapi/petstorev2.json ${project.build.directory}/generated-sources community.flock.wirespec.generated.java.v2 OpenAPIV2 Java false java-v3 convert ${project.basedir}/src/main/openapi/petstorev3.json ${project.build.directory}/generated-sources community.flock.wirespec.generated.java.v3 OpenAPIV3 Java false ``` -------------------------------- ### Rust Code Example Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/rust/fixtures/compileChannelTest.txt Example Rust code for a Queue trait. ```rust use super::super::wirespec::* use regex; pub trait Queue: Wirespec.Channel { fn invoke(message: &str); } #![allow(warnings)] pub mod model; pub mod endpoint; pub mod wirespec; ``` -------------------------------- ### Generate Java code from Wirespec definition Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/getting-started/getting-started.mdx Compiles a Wirespec definition to Java, generating DTOs and endpoint structures. ```bash wirespec compile --input . --language java ``` -------------------------------- ### Indentation Example Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/language/language.mdx Demonstrates the recommended indentation style for Wirespec code. ```wirespec endpoint GetTodos GET /todos -> { 200 -> Todo[] } ``` -------------------------------- ### Python Client Example Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/python/fixtures/compileFullEndpointTest.txt Example of a Python client implementation for a Wirespec endpoint. ```python import enum from .wirespec import T, Wirespec, _raise from .model.Token import Token from .model.PotentialTodoDto import PotentialTodoDto from .model.TodoDto import TodoDto from .model.Error import Error from .endpoint.PutTodo import * from .client.PutTodoClient import PutTodoClient @dataclass class Client(PutTodo.Call): serialization: Wirespec.Serialization transportation: Wirespec.Transportation async def put_todo(self, id: str, done: bool, name: Optional[str], token: Token, refreshToken: Optional[Token], body: PotentialTodoDto) -> Response[Any]: return await PutTodoClient(serialization=self.serialization, transportation=self.transportation).put_todo(id, done, name, token, refreshToken, body) ``` -------------------------------- ### Example Type with Constraints Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/blog/2025-07-16-type-constraints/index.md An example demonstrating how to apply string, integer, and number constraints to a type definition. ```wirespec type Example { string: String(/.{0,50}/g), integer: Integer(0, 10), number: Number(0.0, 5.5) } ``` -------------------------------- ### Compile Command Example Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/plugins/plugins-cli.md An example of how to use the 'compile' command to compile a Wirespec type. ```shell wirespec compile "type SomeType { someField: String }" ``` -------------------------------- ### Pre-Processor Implementation: Kotlin Example Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/plugins/plugins-maven.md Example Kotlin implementation of a pre-processor class. ```kotlin class MyPreProcessor : (String) -> String { override fun invoke(input: String): String { // Process the input and return the result return processedInput } } ``` -------------------------------- ### Install Wirespec Language Server Globally Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/ide/lsp.md Installs the Wirespec language server package globally using npm, making the `wirespec-lsp` binary available on the system's PATH. ```bash npm install -g @flock/wirespec ``` -------------------------------- ### Pre-Processor Implementation: Java Example Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/plugins/plugins-maven.md Example Java implementation of a pre-processor class. ```java public class MyPreProcessor implements Function { @Override public String apply(String input) { // Process the input and return the result return processedInput; } } ``` -------------------------------- ### Run docusaurus locally Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/README.md Command to start the Docusaurus development server. ```bash npm start ``` -------------------------------- ### Generate TypeScript code from Wirespec definition Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/getting-started/getting-started.mdx Compiles a Wirespec definition to TypeScript, generating DTOs and endpoint structures. ```bash wirespec compile --input . --language typescript ``` -------------------------------- ### Integer Constraints Examples Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/blog/2025-07-16-type-constraints/index.md Examples of defining constraints for integer types, specifying minimum and maximum values, or only one bound. ```wirespec // An integer between 0 and 10 (inclusive) integer: Integer(0, 10) // A positive integer positiveInt: Integer(1) // An integer with an upper bound maxInt: Integer(, 100) // Any integer up to 100 ``` -------------------------------- ### Install Wirespec CLI on Linux Source: https://github.com/flock-community/wirespec/blob/master/README.md Instructions for downloading and installing the Wirespec CLI on a Linux system. ```shell curl -L https://github.com/flock-community/wirespec/releases/latest/download/linuxX64.kexe -o wirespec chmod +x wirespec sudo mv ./wirespec /usr/local/bin/wirespec ``` -------------------------------- ### Wirespec definition for Todo resource Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/getting-started/getting-started.mdx Defines a contract for basic CRUD operations of a Todo resource using Wirespec syntax. ```wirespec type TodoDto { id: Integer?, name: String, assignee: UserDto? } type UserDto { name: String, role: Role } enum Role { Admin, Editor, Viewer } endpoint GetTodos GET /api/todos -> { 200 -> TodoDto[] } endpoint GetById GET /api/todos/{id: Integer} -> { 200 -> TodoDto 404 -> String } endpoint CreateTodo POST TodoDto /api/todos -> { 201 -> TodoDto } endpoint DeleteTodo DELETE /api/todos/{id: Integer} -> { 204 -> Unit 404 -> String } endpoint UpdateTodo PUT TodoDto /api/todos/{id: Integer} -> { 200 -> TodoDto } ``` -------------------------------- ### Start Wirespec Language Server with StdIO Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/ide/lsp.md Starts the Wirespec language server, directing its input and output through standard input and standard output (stdio). This is typically used when integrating with editors. ```bash wirespec-lsp --stdio ``` -------------------------------- ### Install Wirespec CLI on macOS Source: https://github.com/flock-community/wirespec/blob/master/README.md Instructions for downloading and installing the Wirespec CLI on a macOS system. ```shell curl -L https://github.com/flock-community/wirespec/releases/latest/download/macosX64.kexe -o wirespec chmod +x wirespec sudo mv ./wirespec /usr/local/bin/wirespec ``` -------------------------------- ### Java Consumer Example Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/integration/integration-avro.mdx Demonstrates how to consume Avro messages from a Kafka topic using Wirespec. ```java @Service public class NotificationConsumer { private static final String TOPIC = "my-topic"; private final ConsumerFactory kafkaConsumerFactory; public NotificationConsumer(ConsumerFactory kafkaConsumerFactory) { this.kafkaConsumerFactory = kafkaConsumerFactory; } public void listen(String groupId, Task listener) { ContainerProperties containerProps = new ContainerProperties(TOPIC); containerProps.setGroupId(groupId); KafkaMessageListenerContainer container = new KafkaMessageListenerContainer<>(kafkaConsumerFactory, containerProps); container.setupMessageListener((MessageListener) data -> { Task task = Task.Avro.from(data.value()); // Handle task }); container.start(); } } ``` -------------------------------- ### Kotlin Consumer Example Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/integration/integration-avro.mdx Demonstrates how to consume Avro messages from a Kafka topic using Wirespec in Kotlin. ```kotlin @Service class NotificationConsumer(private val kafkaConsumerFactory: ConsumerFactory) { companion object { private const val TOPIC = "my-topic" } fun listen(groupId: String, listener: Task?) { val containerProps = ContainerProperties(TOPIC) containerProps.groupId = groupId val container = KafkaMessageListenerContainer(kafkaConsumerFactory, containerProps) container.setupMessageListener(MessageListener { data: ConsumerRecord -> val task = Task.Avro.from(data.value()) // Handle task }) container.start() } } ``` -------------------------------- ### String Constraints Examples Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/blog/2025-07-16-type-constraints/index.md Examples of using regular expressions to define constraints for string types, including length, email format, and date format. ```wirespec // A string with length between 0 and 50 characters string: String(/.{0,50}/g) // An email address email: String(/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/g) // A date in YYYY-MM-DD format date: String(/^\d{4}-\d{2}-\d{2}$/g) ``` -------------------------------- ### Annotations Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/language/language.mdx Examples of applying annotations to types and endpoints for metadata. ```wirespec @Deprecated("No longer used in V2") type User { id: Integer, name: String } @Deprecated("Use GetUserV2 instead") endpoint GetUser GET /users/{id: Integer} -> { 200 -> User } ``` -------------------------------- ### Kotlin Producer Example Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/integration/integration-avro.mdx Demonstrates how to produce Avro messages to a Kafka topic using Wirespec in Kotlin. ```kotlin @Service class NotificationProducer( private val kafkaProducerFactory: ProducerFactory ) : NotificationQueueChannel { companion object { const val TOPIC = "my-topic" } override fun invoke(message: Task) { val template = KafkaTemplate(kafkaProducerFactory) val avro = Task.Avro.to(message) template.send(Companion.TOPIC, avro) } } ``` -------------------------------- ### Java Producer Example Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/integration/integration-avro.mdx Demonstrates how to produce Avro messages to a Kafka topic using Wirespec. ```java @Service public class NotificationProducer implements NotificationQueueChannel { private static final String TOPIC = "my-topic"; private final ProducerFactory kafkaProducerFactory; public NotificationProducer(ProducerFactory kafkaProducerFactory) { this.kafkaProducerFactory = kafkaProducerFactory; } @Override public void invoke(Task message) { KafkaTemplate template = new KafkaTemplate<>(kafkaProducerFactory); GenericData.Record avro = Task.Avro.to(message); template.send(TOPIC, avro); } } ``` -------------------------------- ### Number Constraints Examples Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/blog/2025-07-16-type-constraints/index.md Examples of defining constraints for number types, including decimal numbers, with specified ranges or single bounds. ```wirespec // A number between 0.0 and 5.5 (inclusive) number: Number(0.0, 5.5) // A positive number positiveNum: Number(0.1, _) // A number with an upper bound maxNum: Number(_ , 99.9) // Any number up to 99.9 ``` -------------------------------- ### Multiple Annotations Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/language/language.mdx Example of applying multiple annotations to the same definition. ```wirespec @JsonSerializable("strict") @ValidateInput type CreateUserRequest { name: String, email: String } ``` -------------------------------- ### Tag Record Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/java/fixtures/compileComplexModelTest.txt Represents a tag with validation. ```java package community.flock.wirespec.generated.model; import community.flock.wirespec.java.Wirespec; public record Tag ( String value ) implements Wirespec.Refined { @Override public Boolean validate() { return java.util.regex.Pattern.compile("^[a-z][a-z0-9-]{0,19}$").matcher(value).find(); } @Override public String toString() { return value; } @Override public String value() { return value; } }; ``` -------------------------------- ### Advanced Configuration: Pre-Processing Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/plugins/plugins-maven.md Example of configuring a pre-processor class for Wirespec conversion. ```xml com.example.MyPreProcessor ``` -------------------------------- ### Email Record Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/java/fixtures/compileComplexModelTest.txt Represents an email address with validation. ```java package community.flock.wirespec.generated.model; import community.flock.wirespec.java.Wirespec; public record Email ( String value ) implements Wirespec.Refined { @Override public Boolean validate() { return java.util.regex.Pattern.compile("^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$").matcher(value).find(); } @Override public String toString() { return value; } @Override public String value() { return value; } }; ``` -------------------------------- ### UserAccountPassword Case Class Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/scala/fixtures/compileUnionTest.txt Represents a UserAccount with a username and password. ```scala package community.flock.wirespec.generated.model import community.flock.wirespec.scala.Wirespec import scala.reflect.ClassTag case class UserAccountPassword( val username: String, val password: String ) extends Wirespec.Model with UserAccount { override def validate(): List[String] = List.empty[String] } ``` -------------------------------- ### Department Record Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/java/fixtures/compileComplexModelTest.txt Represents a department with a name and a list of employees, with validation. ```java package community.flock.wirespec.generated.model; import community.flock.wirespec.java.Wirespec; public record Department ( String name, java.util.List employees ) implements Wirespec.Model { @Override public java.util.List validate() { return java.util.stream.IntStream.range(0, employees().size()).mapToObj(i -> employees().get(i).validate().stream().map(e -> "employees[" + i + "]." + e).toList()).flatMap(java.util.Collection::stream).toList(); } }; ``` -------------------------------- ### Compile Wirespec using CLI Source: https://github.com/flock-community/wirespec/blob/master/README.md Example of compiling a Wirespec file into language-specific bindings using the CLI. ```shell wirespec compile ./todo.ws -o ./tmp -l Kotlin ``` -------------------------------- ### User Data Class Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/kotlin/fixtures/compileUnionTest.txt Represents a user with a username and an associated account. ```kotlin package community.flock.wirespec.generated.model import community.flock.wirespec.kotlin.Wirespec import kotlin.reflect.typeOf data class User( val username: String, val account: UserAccount ) : Wirespec.Model { override fun validate(): List = emptyList() } ``` -------------------------------- ### Convert Mojo Usage in pom.xml Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/plugins/plugins-maven.md Example of how to configure the convert mojo in your pom.xml file. ```xml community.flock.wirespec.plugin.maven wirespec-maven-plugin {{WIRESPEC_VERSION}} openapi convert ${project.basedir}/src/main/openapi/specification.json ${project.build.directory}/generated-sources/openapi OpenAPIV3 Java Kotlin ``` -------------------------------- ### Initialize the SDK Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/blog/2025-06-15-bunq-sdk/index.md This snippet shows how to initialize the bunq SDK by providing configuration details such as API key, service name, and public/private key files. ```kotlin val config = Config( apiKey = "your_api_key", serviceName = "YourServiceName", publicKeyFile = File("path/to/public_key.pem"), privateKeyFile = File("path/to/private_key.pem"), ) val signing = Signing(config) val context = initContext(config) val sdk = Sdk(handler(signing, context)) ``` -------------------------------- ### Wirespec Definition Example Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/integration/integration-spring.mdx A simple Wirespec definition for a TodoDto and a GET endpoint. ```wirespec type TodoDto { id: Integer, task: String } endpoint GetTodo GET /api/todos/{id: Integer} -> { 200 -> TodoDto 400 -> String } ``` -------------------------------- ### Advanced Configuration: Source Directory Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/plugins/plugins-maven.md Example of configuring a custom source directory for Wirespec files. ```xml ${project.basedir}/src/wirespec/kotlin ``` -------------------------------- ### Make API Calls Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/blog/2025-06-15-bunq-sdk/index.md This snippet demonstrates how to make API calls using the initialized SDK, including fetching user information and listing bank accounts. ```kotlin // Get user information val userResponse = sdk.rEAD_User(context.userId) val userData = when (userResponse) { is READ_User.Response200 -> userResponse.body is READ_User.Response400 -> error("Cannot read user") } // List bank accounts val accountsResponse = sdk.list_all_MonetaryAccountBank_for_User(context.userId) val accounts = when (accountsResponse) { is List_all_MonetaryAccountBank_for_User.Response200 -> accountsResponse.body is List_all_MonetaryAccountBank_for_User.Response400 -> error("Could not get bank accounts") } ``` -------------------------------- ### UserAccountToken Data Class Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/kotlin/fixtures/compileUnionTest.txt Represents a user account with an authentication token. ```kotlin package community.flock.wirespec.generated.model import community.flock.wirespec.kotlin.Wirespec import kotlin.reflect.typeOf data class UserAccountToken( val token: String ) : Wirespec.Model, UserAccount { override fun validate(): List = emptyList() } ``` -------------------------------- ### UserAccountPassword Data Class Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/kotlin/fixtures/compileUnionTest.txt Represents a user account with username and password. ```kotlin package community.flock.wirespec.generated.model import community.flock.wirespec.kotlin.Wirespec import kotlin.reflect.typeOf data class UserAccountPassword( val username: String, val password: String ) : Wirespec.Model, UserAccount { override fun validate(): List = emptyList() } ``` -------------------------------- ### Context Initialization Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/blog/2025-06-15-bunq-sdk/index.md The `initContext` function handles the handshake process with the bunq API, including key generation, installation, device server creation, and session server creation. ```kotlin fun initContext(config: Config): Context { val signing = Signing(config) val (_, publicKeyPem) = signing.generateRsaKeyPair() val installation = createInstallation(config.serviceName, publicKeyPem) val deviceServer = createDeviceServer(config.serviceName, config.apiKey, installation.Token.token) val serverSession = createSessionServer(config.serviceName, config.apiKey, installation.Token.token) return Context( apiKey = config.apiKey, serviceName = config.serviceName, serverPublicKey = installation.ServerPublicKey.server_public_key, deviceId = deviceServer.Id.id, sessionId = serverSession.Id.id, sessionToken = serverSession.Token.token, userId = serverSession.UserPerson.id, // ... other properties ) } ``` -------------------------------- ### Queue Channel Definition Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/kotlin/fixtures/compileChannelTest.txt Example of a channel definition for a queue that accepts String messages. ```kotlin package community.flock.wirespec.generated.channel import community.flock.wirespec.kotlin.Wirespec import kotlin.reflect.typeOf interface Queue : Wirespec.Channel { fun invoke(message: String) } ``` -------------------------------- ### UserAccount Interface Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/kotlin/fixtures/compileUnionTest.txt Defines a sealed interface for different types of user accounts. ```kotlin package community.flock.wirespec.generated.model import community.flock.wirespec.kotlin.Wirespec import kotlin.reflect.typeOf sealed interface UserAccount ``` -------------------------------- ### Navigate to the docs folder Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/README.md Command to navigate to the documentation directory. ```bash cd src/site/docs ``` -------------------------------- ### Employee Record Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/java/fixtures/compileComplexModelTest.txt Represents an employee with name, age, contact info, and tags, with validation. ```java package community.flock.wirespec.generated.model; import community.flock.wirespec.java.Wirespec; public record Employee ( String name, EmployeeAge age, ContactInfo contactInfo, java.util.List tags ) implements Wirespec.Model { @Override public java.util.List validate() { return java.util.stream.Stream.of((!age().validate() ? java.util.List.of("age") : java.util.List.of()), contactInfo().validate().stream().map(e -> "contactInfo." + e).toList(), java.util.stream.IntStream.range(0, tags().size()).mapToObj(i -> (!tags().get(i).validate() ? java.util.List.of("tags[" + i + "]") : java.util.List.of())).flatMap(java.util.Collection::stream).toList()).flatMap(java.util.Collection::stream).toList(); } }; ``` -------------------------------- ### Wirespec Maven Plugin Configuration Source: https://github.com/flock-community/wirespec/blob/master/examples/maven-spring-custom/README.md XML configuration for the Wirespec Maven plugin, specifying input/output directories, a custom emitter class, file extension, and splitting behavior. It also includes the necessary dependency for the custom emitter. ```xml community.flock.wirespec.plugin.maven wirespec-maven-plugin ${wirespec-maven-plugin.version} custom custom ${project.basedir}/src/main/wirespec ${project.build.directory}/generated-sources/java/hello community.flock.wirespec.example.maven.custom.emit.CustomEmitter java true community.flock.wirespec.example.maven_plugin_custom emitter x.x.x ``` -------------------------------- ### Empty Type Example Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/kotlin/fixtures/testEmitterEmptyType.txt An example of an empty type definition in Kotlin using Wirespec. ```kotlin package community.flock.wirespec.generated.model import community.flock.wirespec.kotlin.Wirespec import kotlin.reflect.typeOf data object TodoWithoutProperties : Wirespec.Model { override fun validate(): List = emptyList() } ``` -------------------------------- ### Client Implementation for GetTodos Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/python/fixtures/compileMinimalEndpointTest.txt Provides a client implementation for the 'GetTodos' endpoint, abstracting the serialization and transportation details. ```python from __future__ import annotations import re from abc import ABC, abstractmethod from dataclasses import dataclass from typing import Any, Generic, List, Optional import enum from .wirespec import T, Wirespec, _raise from .model.TodoDto import TodoDto from .endpoint.GetTodos import * from .client.GetTodosClient import GetTodosClient @dataclass class Client(GetTodos.Call): serialization: Wirespec.Serialization transportation: Wirespec.Transportation async def get_todos(self) -> Response[Any]: return await GetTodosClient(serialization=self.serialization, transportation=self.transportation).get_todos() ``` -------------------------------- ### Install Wirespec CLI as Dev Dependency Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/plugins/plugins-npm.md Installs the Wirespec NPM package as a development dependency in your project. ```bash npm install --save-dev @flock/wirespec ``` -------------------------------- ### Install Wirespec CLI on macOS Arm Source: https://github.com/flock-community/wirespec/blob/master/README.md Instructions for downloading and installing the Wirespec CLI on an Apple Silicon (M1/M2) macOS system. ```shell curl -L https://github.com/flock-community/wirespec/releases/latest/download/macosArm64.kexe -o wirespec chmod +x wirespec sudo mv ./wirespec /usr/local/bin/wirespec ``` -------------------------------- ### Running the Convert Goal Directly Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/plugins/plugins-maven.md Command to run the convert mojo directly using Maven. ```bash mvn wirespec:convert ``` -------------------------------- ### Gradle Plugin Usage Source: https://github.com/flock-community/wirespec/blob/master/src/plugin/gradle/Readme.md Examples of how to use the Gradle plugin to compile wirespec files into different formats and languages. ```kotlin tasks.register("wirespec-kotlin") { input = layout.projectDirectory.dir("wirespec") output = layout.buildDirectory.dir("generated") packageName = "community.flock.wirespec.custom" languages = listOf(Language.Kotlin) } tasks.register("wirespec-openapi") { input = layout.projectDirectory.file("openapi/petstorev3.json") output = layout.buildDirectory.dir("generated") format = Format.OpenAPIV3 packageName = "community.flock.wirespec.openapi" languages = listOf(Language.Kotlin) } tasks.register("wirespec-custom") { input = layout.projectDirectory.dir("wirespec") output = layout.buildDirectory.dir("generated") packageName = "community.flock.wirespec.wirespec" emitter = KotlinSerializableEmitter::class.java shared = KotlinShared.source extension = "kt" } ``` -------------------------------- ### Maven and Gradle build commands Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/integration/integration-avro.mdx Commands to compile Wirespec definitions using Maven and Gradle. ```bash # For Maven mvn install # For Gradle ./gradlew wirespec-avro-java # For Java ./gradlew wirespec-avro-kotlin # For Kotlin ``` -------------------------------- ### GetTodosClient Implementation Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/kotlin/fixtures/compileMinimalEndpointTest.txt Client implementation for the GetTodos endpoint, handling request and response transformations. ```kotlin package community.flock.wirespec.generated.client import community.flock.wirespec.kotlin.Wirespec import kotlin.reflect.typeOf import community.flock.wirespec.generated.model.TodoDto import community.flock.wirespec.generated.endpoint.GetTodos data class GetTodosClient( val serialization: Wirespec.Serialization, val transportation: Wirespec.Transportation ) : GetTodos.Call { override suspend fun getTodos(): GetTodos.Response<*> { val request = GetTodos.Request val rawRequest = GetTodos.toRawRequest(serialization, request) val rawResponse = transportation.transport(rawRequest) return GetTodos.fromRawResponse(serialization, rawResponse) } } ``` -------------------------------- ### Clone the repo and set up a new branch Source: https://github.com/flock-community/wirespec/blob/master/CONTRIBUTING.md Steps to clone the Wirespec repository and create a new branch for your changes. ```bash git clone https://github.com/flock-community/wirespec.git cd wirespec # Create a branch for your changes git checkout -b feature/my-awesome-feature ``` -------------------------------- ### Comments Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/language/language.mdx Examples of single-line (end-of-line) and multi-line (block) comments in Wirespec. ```wirespec // This is an end-of-line comment endpoint GetTodos GET /todos -> { 200 -> Todo[] } /* This is a block comment * on multiple lines */ type Todo { id: Integer, title: String, completed: Boolean } ``` -------------------------------- ### UserAccountToken Case Class Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/scala/fixtures/compileUnionTest.txt Represents a UserAccount with a token. ```scala package community.flock.wirespec.generated.model import community.flock.wirespec.scala.Wirespec import scala.reflect.ClassTag case class UserAccountToken( val token: String ) extends Wirespec.Model with UserAccount { override def validate(): List[String] = List.empty[String] } ``` -------------------------------- ### PhoneNumber Record Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/java/fixtures/compileComplexModelTest.txt Represents a phone number with validation. ```java package community.flock.wirespec.generated.model; import community.flock.wirespec.java.Wirespec; public record PhoneNumber ( String value ) implements Wirespec.Refined { @Override public Boolean validate() { return java.util.regex.Pattern.compile("^\\+[1-9]\\d{1,14}$").matcher(value).find(); } @Override public String toString() { return value; } @Override public String value() { return value; } }; ``` -------------------------------- ### Wirespec Gradle Plugin Configuration Source: https://github.com/flock-community/wirespec/blob/master/examples/gradle-ktor/README.md Configuration block for the Wirespec Gradle Plugin, specifying input Wirespec files and output directories for Kotlin and TypeScript code generation. ```gradle wirespec { input = "$projectDir/src/main/wirespec" kotlin { packageName = "community.flock.wirespec.generated" output = "$buildDir/generated/community/flock/wirespec/generated" } typescript { output = "$projectDir/src/main/typescript/generated" } } tasks.build { dependsOn("wirespec") } ``` -------------------------------- ### SDK Configuration Class Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/blog/2025-06-15-bunq-sdk/index.md Defines the configuration parameters for the SDK, including API key, service name, and file paths. ```kotlin data class Config( val serviceName: String, val apiKey: String, val privateKeyFile: File = File("../private_key.pem"), val publicKeyFile: File = File("../public_key.pem"), val userAgent: String? = null, val cacheControl: String? = null, val language: String? = null, val region: String? = null, val clientRequestId: String? = null, val geolocation: String? = null, ) ``` -------------------------------- ### EmployeeAge Record Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/java/fixtures/compileComplexModelTest.txt Represents an employee's age with validation. ```java package community.flock.wirespec.generated.model; import community.flock.wirespec.java.Wirespec; public record EmployeeAge ( Long value ) implements Wirespec.Refined { @Override public Boolean validate() { return 18 <= value && value <= 65; } @Override public String toString() { return value.toString(); } @Override public Long value() { return value; } }; ``` -------------------------------- ### Detailed Compile Goal Configuration Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/plugins/plugins-maven.md An in-depth example of the compile mojo configuration within the pom.xml, specifying input, output, languages, and other parameters. ```xml community.flock.wirespec.plugin.maven wirespec-maven-plugin {{WIRESPEC_VERSION}} wirespec-compile compile ${project.basedir}/src/main/wirespec ${project.build.directory}/generated-sources/wirespec Java Kotlin TypeScript com.example.generated true true ``` -------------------------------- ### Client Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/scala/fixtures/compileFullEndpointTest.txt Generated Scala client entry point. ```scala package community.flock.wirespec.generated import community.flock.wirespec.scala.Wirespec import scala.reflect.ClassTag import community.flock.wirespec.generated.model.Token import community.flock.wirespec.generated.model.PotentialTodoDto import community.flock.wirespec.generated.model.TodoDto import community.flock.wirespec.generated.model.Error import community.flock.wirespec.generated.endpoint.PutTodo import community.flock.wirespec.generated.client.PutTodoClient case class Client( val serialization: Wirespec.Serialization, val transportation: Wirespec.Transportation ) extends PutTodo.Call[[A] =>> A] { override def putTodo(id: String, done: Boolean, name: Option[String], token: Token, refreshToken: Option[Token], body: PotentialTodoDto): PutTodo.Response[?] = new PutTodoClient( serialization = serialization, transportation = transportation ).putTodo(id, done, name, token, refreshToken, body) } ``` -------------------------------- ### Annotations with Named Attributes Source: https://github.com/flock-community/wirespec/blob/master/src/site/docs/docs/language/language.mdx Examples of annotations with named attributes and different value types. ```wirespec @Security(role: "admin", level: 1) @RateLimit(requests: 100, period: "hour") endpoint AdminEndpoint GET /admin -> { 200 -> AdminData } @Validate(min: 1, max: 100, required: true) type Score { value: Integer } ``` -------------------------------- ### User Case Class Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/scala/fixtures/compileUnionTest.txt Represents a User with a username and an associated UserAccount. ```scala package community.flock.wirespec.generated.model import community.flock.wirespec.scala.Wirespec import scala.reflect.ClassTag case class User( val username: String, val account: UserAccount ) extends Wirespec.Model { override def validate(): List[String] = List.empty[String] } ``` -------------------------------- ### Response Matching and RawResponse Creation Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/scala/fixtures/compileFullEndpointTest.txt Demonstrates how to match different response types (Response200, Response201, Response500) and construct a Wirespec.RawResponse accordingly, including serialization of headers and body. ```scala response match { case r: Response200 => { new Wirespec.RawResponse( statusCode = r.status, headers = Map.empty, body = Some(serialization.serializeBody(r.body, scala.reflect.classTag[TodoDto])) ) } case r: Response201 => { new Wirespec.RawResponse( statusCode = r.status, headers = Map("token" -> serialization.serializeParam[Token](r.headers.token, scala.reflect.classTag[Token]), "refreshToken" -> (r.headers.refreshToken.map(it => serialization.serializeParam[Token](it, scala.reflect.classTag[Token])).getOrElse(List.empty[String]))), body = Some(serialization.serializeBody(r.body, scala.reflect.classTag[TodoDto])) ) } case r: Response500 => { new Wirespec.RawResponse( statusCode = r.status, headers = Map.empty, body = Some(serialization.serializeBody(r.body, scala.reflect.classTag[Error])) ) } case _ => { throw new IllegalStateException(("Cannot match response with status: " + response.status)) } } } ``` -------------------------------- ### Tag Model Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/scala/fixtures/compileComplexModelTest.txt Defines a refined String type for tags with validation. ```scala package community.flock.wirespec.generated.model import community.flock.wirespec.scala.Wirespec import scala.reflect.ClassTag case class Tag( override val value: String ) extends Wirespec.Refined[String] { override def validate(): Boolean = "^[a-z][a-z0-9-]{0,19}$".r.findFirstIn(value).isDefined override def toString(): String = value } ``` -------------------------------- ### Wirespec Maven Plugin Configuration Source: https://github.com/flock-community/wirespec/blob/master/examples/maven-spring-avro/README.md XML configuration for the wirespec-maven-plugin, including dependencies and execution details for generating Java code with Avro integration. ```xml community.flock.wirespec.plugin.maven wirespec-maven-plugin 0.0.0-SNAPSHOT community.flock.wirespec.integration avro-jvm 0.0.0-SNAPSHOT java custom ${project.basedir}/src/main/wirespec ${project.build.directory}/generated-sources community.flock.wirespec.integration.avro.java.emit.AvroEmitter Java java community.flock.wirespec.generated.examples.spring ``` -------------------------------- ### Company Record Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/java/fixtures/compileComplexModelTest.txt Represents a company with a name and a list of departments, with validation. ```java package community.flock.wirespec.generated.model; import community.flock.wirespec.java.Wirespec; public record Company ( String name, java.util.List departments ) implements Wirespec.Model { @Override public java.util.List validate() { return java.util.stream.IntStream.range(0, departments().size()).mapToObj(i -> departments().get(i).validate().stream().map(e -> "departments[" + i + "]." + e).toList()).flatMap(java.util.Collection::stream).toList(); } }; ``` -------------------------------- ### Request and Response Structures for GetTodos Endpoint Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/python/fixtures/compileMinimalEndpointTest.txt Defines the data structures for the 'GetTodos' endpoint, including Path, Queries, Headers, Request, and various Response types. ```python from __future__ import annotations import re from abc import ABC, abstractmethod from dataclasses import dataclass from typing import Any, Generic, List, Optional import enum from ..wirespec import T, Wirespec, _raise from ..model.TodoDto import TodoDto @dataclass class Path(Wirespec.Path): pass @dataclass class Queries(Wirespec.Queries): pass @dataclass class RequestHeaders(Wirespec.Request.Headers): pass @dataclass class Request(Wirespec.Request[None]): path: Path method: Wirespec.Method queries: Queries headers: RequestHeaders body: None def __init__(self): self.path = Path() self.method = Wirespec.Method.GET self.queries = Queries() self.headers = RequestHeaders() self.body = None class Response(Wirespec.Response[T], Generic[T]): pass class Response2XX(Response[T], Generic[T]): pass class ResponseListTodoDto(Response[list[TodoDto]]): pass @dataclass class Response200Headers(Wirespec.Response.Headers): pass @dataclass class Response200(Response2XX[list[TodoDto]], ResponseListTodoDto): status: int headers: Response200Headers body: list[TodoDto] def __init__( self, body: list[TodoDto], ): self.status = 200 self.headers = Response200Headers() self.body = body ``` -------------------------------- ### UserAccount Interface Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/java/fixtures/compileUnionTest.txt Generated Java interface for the UserAccount union type. ```java package community.flock.wirespec.generated.model; import community.flock.wirespec.java.Wirespec; public sealed interface UserAccount permits UserAccountPassword, UserAccountToken {} ``` -------------------------------- ### CLI Usage - Generate Source: https://github.com/flock-community/wirespec/blob/master/src/plugin/npm/README.md Command to create a new Wirespec file. ```bash wirespec generate ``` -------------------------------- ### TestNum0 Refined Type Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/scala/fixtures/compileRefinedTest.txt A refined type for TestNum0 that always validates. ```scala package community.flock.wirespec.generated.model import community.flock.wirespec.scala.Wirespec import scala.reflect.ClassTag case class TestNum0( override val value: Double ) extends Wirespec.Refined[Double] { override def validate(): Boolean = true override def toString(): String = value.toString } ``` -------------------------------- ### TestNum Refined Type Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/scala/fixtures/compileRefinedTest.txt A refined type for TestNum that always validates. ```scala package community.flock.wirespec.generated.model import community.flock.wirespec.scala.Wirespec import scala.reflect.ClassTag case class TestNum( override val value: Double ) extends Wirespec.Refined[Double] { override def validate(): Boolean = true override def toString(): String = value.toString } ``` -------------------------------- ### Stage 2: Convert (Parser AST → IR) Function Source: https://github.com/flock-community/wirespec/blob/master/CLAUDE.md The `IrConverter.kt` maps each parser `Definition` to an IR `File` tree. The entry point dispatches by definition type. ```kotlin fun DefinitionWirespec.convert(): File = when (this) { is TypeWirespec -> convert() is EnumWirespec -> convert() is UnionWirespec -> convert() is RefinedWirespec -> convert() is ChannelWirespec -> convert() is EndpointWirespec -> convert() } ``` -------------------------------- ### TestInt0 Refined Type Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/scala/fixtures/compileRefinedTest.txt A refined type for TestInt0 that always validates. ```scala package community.flock.wirespec.generated.model import community.flock.wirespec.scala.Wirespec import scala.reflect.ClassTag case class TestInt0( override val value: Long ) extends Wirespec.Refined[Long] { override def validate(): Boolean = true override def toString(): String = value.toString } ``` -------------------------------- ### TestInt Refined Type Source: https://github.com/flock-community/wirespec/blob/master/src/compiler/emitters/scala/fixtures/compileRefinedTest.txt A refined type for TestInt that always validates. ```scala package community.flock.wirespec.generated.model import community.flock.wirespec.scala.Wirespec import scala.reflect.ClassTag case class TestInt( override val value: Long ) extends Wirespec.Refined[Long] { override def validate(): Boolean = true override def toString(): String = value.toString } ```