https://github.com/wiremock/protobuf-extension-example
An example WireMock extension to encode/decode protobuf request/responses (non-gRPC)
https://github.com/wiremock/protobuf-extension-example
Last synced: 19 days ago
JSON representation
An example WireMock extension to encode/decode protobuf request/responses (non-gRPC)
- Host: GitHub
- URL: https://github.com/wiremock/protobuf-extension-example
- Owner: wiremock
- License: apache-2.0
- Created: 2026-04-23T13:31:20.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-30T06:48:28.000Z (2 months ago)
- Last Synced: 2026-04-30T08:20:37.807Z (2 months ago)
- Language: Java
- Size: 77.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# WireMock Protobuf Extension
A [WireMock](https://wiremock.org/) extension that adds Protocol Buffers support, allowing you to stub and verify protobuf-encoded HTTP APIs using familiar JSON matching.
## How it works
The extension automatically:
1. **Decodes** incoming protobuf request bodies into JSON so you can use WireMock's standard JSON matchers (`equalToJson`, `matchingJsonPath`, etc.)
2. **Encodes** JSON response bodies back into protobuf wire format when the request has a protobuf content type
Requests with `Content-Type: application/x-protobuf` or `application/protobuf` are processed. All other requests pass through unmodified.
## Prerequisites
- Java 17+
- WireMock 4.x
## Building
```bash
./gradlew shadowJar
```
The shadow JAR at `build/libs/wiremock-protobuf-extension--all.jar` includes protobuf and all its transitive dependencies, shaded to avoid classpath conflicts.
## Usage
### Adding the extension
Place the shadow JAR on WireMock's classpath. The extension is loaded automatically via `ExtensionFactory` service loading.
Or register it programmatically:
```java
WireMockServer wm = new WireMockServer(
wireMockConfig()
.extensions(new ProtobufExtensionFactory())
);
```
### Defining your protobuf schema
Place your `.proto` files in `src/main/proto`. The build generates a descriptor set at `protobuf/descriptor.desc` which the extension uses at runtime to dynamically parse messages.
### Stubbing
Define stubs with JSON bodies as normal -- the extension handles the protobuf encoding:
```java
stubFor(
post(urlPathEqualTo("/api/things"))
.withRequestBody(equalToJson("{ \"name\": \"Widget\", \"quantity\": 3 }"))
.willReturn(ok().withBody("{ \"id\": \"123\", \"name\": \"Widget\", \"quantity\": 5 }"))
);
```
### Verification
Verify requests using JSON matchers against the decoded protobuf body:
```java
verify(
postRequestedFor(urlPathEqualTo("/api/things"))
.withRequestBody(matchingJsonPath("$.name", equalTo("Widget")))
);
```
### Response templating
The extension works with WireMock's response templating:
```java
stubFor(
post(urlPathEqualTo("/api/things"))
.willReturn(ok()
.withBody("{ \"id\": \"789\", \"name\": \"{{jsonPath request.body '$.name'}}\" }")
.withTransformers("response-template"))
);
```
## Custom descriptor path
By default the extension loads the descriptor from `/protobuf/descriptor.desc` on the classpath. To use a different path:
```java
new ProtobufExtensionFactory("/custom/path/descriptor.desc")
```
## License
Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.