restdocs-wiremock

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

restdocs-wiremock

★ 79 Open GitHub ↗

Spring REST Docs WireMock Integration

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Spring REST Docs WireMock Integration

[![oss lifecycle](https://img.shields.io/badge/oss_lifecycle-maintenance-yellow.svg)]()
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ePages-de_restdocs-wiremock&metric=coverage)](https://sonarcloud.io/summary/new_code?id=ePages-de_restdocs-wiremock)
![](https://img.shields.io/github/license/ePages-de/restdocs-wiremock.svg?branch=master)

This is a plugin for auto-generating [WireMock](http://wiremock.org/) stubs
as part of documenting your REST API with [Spring REST Docs](http://projects.spring.io/spring-restdocs/).

The basic idea is to use the requests and responses from the integration tests as stubs for testing your client's
API contract. The mock templates can be packaged as jar files and be published into your company's
artifact repository for this purpose.

Details and background information can be read on our [ePages Developer Blog](https://developer.epages.com/blog/2016/07/14/wiremock.html).

- [Contents](#contents)
- [Versions](#versions)
- [How to include `restdocs-wiremock` into your server project](#how-to-include-restdocs-wiremock-into-your-server-project)
    - [Dependencies](#dependencies)
    - [Producing snippets](#producing-snippets)
    - [The WireMock stubs jar](#the-wiremock-stubs-jar)
- [How to use WireMock in your client tests](#how-to-use-wiremock-in-your-client-tests)
    - [Dependencies](#dependencies-1)
    - [Configuring your test to use the WireMock stubs](#configuring-your-test-to-use-the-wiremock-stubs)
- [Building from source](#building-from-source)
- [Publishing](#publishing)
- [Other resources](#other-resources)

## Contents

This repository consists of two libraries:

* `restdocs-wiremock`: The library to extend Spring REST Docs with WireMock stub snippet generation.
* `wiremock-spring-boot-starter`: A spring boot starter which adds a `WireMockServer` to your client's ApplicationContext for integration testing.
  This is optional, but highly recommended when verifying your client contract in a SpringBootTest.

## Versions

There are multiple major versions of the libraries in different branches.
The following table provides an overview which "restdocs-wiremock" release branch is to be used for microservices on specific Spring Boot versions.

| restdocs-wiremock version                                                     | Spring Boot version | Java version |
|-----------------------------------------------------------------------|---------------------|--------------|
| [1.x.x](https://github.com/ePages-de/restdocs-wiremock/releases?q=1.) | 3.3.x               | 21           |
| [0.x.x](https://github.com/ePages-de/restdocs-wiremock/releases?q=0.) | 2.7.x               | 17           |

## How to include `restdocs-wiremock` into your server project

### Dependencies

The project is published on Maven Central, so firstly, you need to add `mavenCentral` as package
repository for your project.

Then, add `restdocs-wiremock` as a dependency in test scope. As `restdocs-wiremock` only depends on `spring-restdocs-core`,
you also need to add either `spring-restdocs-mockmvc` or `spring-restdocs-restassured`, depending on your test scenario.
It is recommended to use the `spring-boot` gradle plugin to enable dependency management from the Spring IO Platform.

In gradle it would look like this:

```groovy
dependencies {
  testCompile('com.epages:restdocs-wiremock:1.0.0')
  testCompile('org.springframework.restdocs:spring-restdocs-mockmvc')
}
```

When using maven:

```xml
<dependency>
	<groupId>com.epages</groupId>
	<artifactId>restdocs-wiremock</artifactId>
	<version>1.0.0</version>
	<scope>test</scope>
</dependency>
<dependency>
	<groupId>org.springframework.restdocs</groupId>
	<artifactId>spring-restdocs-mockmvc</artifactId>
	<scope>test</scope>
</dependency>
```

### Producing snippets

During REST Docs run, snippets like the one below are generated and put into a dedicated jar file, which you can publish into your artifact repository.

Integration into your test code is as simple as adding `wiremockJson()` from `com.epages.restdocs.WireMockDocumentation`
to the `document()` calls for Spring REST Docs. For example:

```java
@RunWith(SpringJUnit4ClassRunner.class)
//...
class ApiDocumentation {
    // ... the usual test setup.
    void testGetSingleNote() {
        this.mockMvc.perform(get("/notes/1").accept(MediaType.APPLICATION_JSON))
        .andExpect(status().isOk())
        .andDo(document("get-note",
          wiremockJson(),
          responseFields( ... )
        ));
    }
}
```

The snippet below is the resulting snippet of a `200 OK` response to `/notes/1`, with
the response body as provided by the integration test.

```json
{
  "request" : {
    "method" : "GET",
    "urlPath" : "/notes/1"
  },
  "response" : {
    "status" : 200,
    "headers" : {
      "Content-Type" : [ "application/hal+json" ],
      "Content-Length" : [ "344" ]
    },
    "body" : "{\n  \"title\" : \"REST maturity model\",\n  \"body\" : \"http://martinfowler.com/articles/richardsonMaturityModel.html\",\n  \"_links\" : {\n    \"self\" : {\n      \"href\" : \"http://localhost:8080/notes/1\"\n    },\n    \"note\" : {\n      \"href\" : \"http://localhost:8080/notes/1\"\n    },\n    \"tags\" : {\n      \"href\" : \"http://localhost:8080/notes/1/tags\"\n    }\n  }\n}"
  }
}
```

#### More flexible request matching using `urlPathPattern`

The above snippet has a shortcoming. WireMock will only match a request if the url matches the complete path, including the id.
This is really inflexible.
We can do better by using `RestDocumentationRequestBuilders` to construct the request using a url template, instead of `MockMvcRequestBuilders`.

```java
@RunWith(SpringJUnit4ClassRunner.class)
//...
class ApiDocumentation {
    // ... the usual test setup.
    void testGetSingleNote() {
        this.mockMvc.perform(RestDocumentationRequestBuilders.get("/notes/{id}", 1)
          .accept(MediaType.APPLICATION_JSON))
        .andExpect(status().isOk())
        .andDo(document("get-note",
          wiremockJson(),
          responseFields( ... )
        ));
    }
}
```

This generates a snippet that uses `urlPathPattern` instead if `urlPath`.
So WireMock would match a request with any id value.

```json
{
  "request" : {
    "method" : "GET",
    "urlPathPattern" : "/notes/[^/]+"
  },
  "response" : {
    //...
  }
}
```

#### Response Templating

WireMock stubs with static responses are too inflexible in many use cases. That is why WireMock offers [Response Templating](http://wiremock.org/docs/response-templating/). Response Templating allows us to make our responses more dynamic by using expressions instead of static values.

`restdocs-wiremock` allows us to use response template expressions:

```java
this.mockMvc.perform(get("/notes/{id}", id))
  .andDo(document("get-note",
    wiremockJson(idFieldReplacedWithPathParameterValue()),
    //..
));
```

`idFieldReplacedWithPathParameterValue()` is a convenience method offered by `WireMockDocumentation` for the common use case to replace the `id` field in a response with the value of the second path segment.

The following variant would give the same result:

```java
wiremockJson(templatedResponseField("id").replacedWithWireMockTemplateExpression("request.requestLine.pathSegments.[1]"));
```

We can also address the path parameter by the URI template name.:
```java
wiremockJson(templatedResponseField("id").replacedWithUriTemplateVariableValue("id");)
```

The resulting stub contains the expression and WireMock will replace the `id` field with the value of the path segment when serving a response based on this stub.

```json
{
  "request" : {
    "method" : "GET",
    "urlPattern" : "/notes/[^/]+"
  },
  "response" : {
    "transformers" : [ "response-template" ],
    "body" : "{\"id\":\"{{request.requestLine.pathSegments.[1]}}\",\"title\":\"REST maturity model\"}",
    "status" : 200
  }
}
```

WireMock also offers expressions to generate random values.

```java
wiremockJson(templatedResponseField("id").replacedWithWireMockTemplateExpression("randomValue length=33 type='ALPHANUMERIC'")
```

Also replacing date values often comes in handy:

```java
wiremockJson(templatedResponseField("date").replacedWithWireMockTemplateExpression("now")
```

### The WireMock stubs jar

On the server side you need to collect the WireMock stubs and publish them into an artifact repository.
In gradle this can be achieved by a custom jar task.

```groovy
task wiremockJar(type: Jar) {
	description = 'Generates the jar file containing the wiremock stubs for your REST API.'
	group = 'Build'
	classifier = 'wiremock'
	dependsOn project.tasks.test
	from (snippetsDir) {
		include '**/wiremock-stub.json'
		into "wiremock/${project.name}/mappings"
	}
}
```

On the client side, add a dependency to the test-runtime to the jar containing the WireMock stubs. After
that, the JSON files can be accessed as classpath resources.

```groovy
testRuntime (group:'com.epages', name:'restdocs-server', version:'1.0.0', classifier:'wiremock', ext:'jar')
```

## How to use WireMock in your client tests

Integrating a WireMock server can easily be achieved by including our `wiremock-spring-boot-starter` into your project.
It adds a `wireMockServer` bean, which you can auto-wire in your test code. By default, we start WireMock on a dynamic port,
and set a `wiremock.port` property to the port WireMock is running on. This property can be used to point your clients
to the location of the `WireMock` server.

Services based on `spring-cloud-netflix`, i.e. using `feign` and `ribbon`, are auto-configured for you.

### Dependencies

To add a dependency via gradle, extend your `build.gradle` with the following line:

```groovy
testCompile('com.epages:wiremock-spring-boot-starter:1.0.0')
```

When using maven, add the following dependency in test scope.

```xml
<dependency>
	<groupId>com.epages</groupId>
	<artifactId>wiremock-spring-boot-starter</artifactId>
	<version>1.0.0</version>
	<scope>test</scope>
</dependency>
```

*Important note for Spring Cloud users*: The BOM produced by Spring Cloud includes a transitive resolution of WireMock
version 1.55, (via `spring-cloud-aws` -> `aws-java-sdk-core` -> `wiremock (test)`). As versions from BOM always override
transitive versions coming in through maven dependencies, you need to add an explicit dependency on WireMock 2.x to your
project, like shown in the following gradle example:

```groovy
  testCompile('com.github.tomakehurst:wiremock:2.10.1')
```

### Configuring your test to use the WireMock stubs

Here is an excerpt of the sample test from a restdocs client project to illustrate the usage.

```java
@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = { ClientApplication.class })
@ActiveProfiles("test") // (1)
@WireMockTest(stubPath = "wiremock/restdocs-server") // (2)
public class NoteServiceTest {

@Autowired
    private WireMockServer wireMockServer; // (3)

....
}
```

1. Configure your test to point to your WireMock server.
   In our example we are using a Spring Expression inside `application-test.properties` to point our noteservice to
   WireMock: `noteservice.baseUri=http://localhost:${wiremock.port}/`
2. The `@WireMockTest` annotation enables the `wireMockServer` bean, which can be accessed
   from your test's application context. By default, it starts a WireMockServer on a dynamic port, but you could also
   set it to a fixed port. The `stubPath` property can be used to point to a classpath resource folder that
   holds your json stubs.
3. If you want, you can auto-wire the `WireMockServer` instance, and re-configure it, just as described in the official
   [WireMock documentation](http://wiremock.org/).

It is possible to read-in a subset of mappings for each test, by repeating the `@WireMockTest` annotation on the test method.
The `stubPath` is concatenated from the values given on the test class and the test method, just as a `@RequestMapping` annotation in Spring would.
In the example given below, the resulting stubPath provided to WireMock is composed as `wiremock/myservice/specific-mappings`.

```java
@WireMockTest(stubPath = "wiremock/myservice")
public class MyTest {
    @Test
    @WireMockTest(stubPath = "specific-mappings")
    public void testDifferentMappings() {
     ....
    }
```

## Building from source

This project uses JDK 21, with source compatibility for Java 21.
The JDK can be used via [SDKMAN!](https://sdkman.io/).

Please execute at least step 1 + 2 if before importing restdocs-wiremock into your IDE.

(1) Publish the current restdocs-wiremock library code into your local maven repository.

```shell
./gradlew restdocs-wiremock:build restdocs-wiremock:publishToMavenLocal
```

(2)  Run the server tests, which uses the WireMock integration into Spring REST Docs. As a result, there is a `restdocs-server-wiremock` jar file in your local maven repository. Mind that this jar only contains a set of json files without explicit dependency on WireMock itself.

```shell
./gradlew restdocs-server:build restdocs-server:publishToMavenLocal
```

(3) Run the client tests, that expect a specific API from the server. By mocking a server via WireMock the client can be tested in isolation, but would notice a breaking change.

```shell
./gradlew restdocs-client:build
```

## Publishing

Given that the `master` branch on the upstream repository is in the state from which you want to create a release, execute the following steps:

**(1) [Create release via the GitHub UI](https://github.com/ePages-de/restdocs-wiremock/releases/new)**

Use the intended version number as "Tag version".

This will automatically trigger a GitHub Action build which publishes the JAR files for this release to Sonatype.

**(2) Login to Sonatype**

**(3) Close the staging repository**

Select the generated staging repository and close it.
Check that there are no errors afterwards (e.g. missing signatures or Javadoc JARs).

**(4) Release the repository**

Select the generated staging repository and publish it.
After few minutes, the release should be available in the ["Public Repositories" of ePages](https://oss.sonatype.org/service/local/repo_groups/public/content/com/epages/restdocs-wiremock/maven-metadata.xml).

**(5) Update documentation**

Create a new commit which replaces the previous version number with the new version number in this `README` file.

## Other resources

- [gradle-nexus/publish-plugin](https://github.com/gradle-nexus/publish-plugin)
- [allegro/axion-release-plugin](https://axion-release-plugin.readthedocs.io)
- [Maven Publish Plugin](https://docs.gradle.org/current/userguide/publishing_maven.html)
- A similar approach is taken by [Spring Cloud Contract](https://cloud.spring.io/spring-cloud-contract/)

restdocs-wiremock

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README