Skip to content
A library that tests if the implementation of a REST-API meets its specification.
Branch: master
Clone or download
Latest commit 7059c73 Mar 18, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
core Fixed OpenApiConverter: Parameters referenced from components are not… Mar 12, 2019
docs Moved module specific markdown files from docs to their respective fo… Mar 14, 2019
gradle/wrapper Split project into gradle modules which closes #13 Feb 19, 2019
raml Activated missing features in RamlConverter Mar 18, 2019
spring Moved module specific markdown files from docs to their respective fo… Mar 14, 2019
.gitignore Added out/ folder of the modules to .gitignore Mar 12, 2019
.travis.yml Added jdk11 to ci build Feb 13, 2019
build.gradle Set bugfix version Mar 18, 2019
gradlew Split project into gradle modules which closes #13 Feb 19, 2019


Build Status Maven Central Version

Hikaku (比較) is japanese and means "comparison". This library tests if a REST-API implementation meets its specification.

If you create your REST-API contract-first without using any type of generation, you have to make sure that specification and implementation don't diverge. The aim of this project is to meet this need and offer a mechanism to check specification and implementation for equality without having to create requests which are fired against a mock server. So this library won't check the behavior of the API, but the structural correctness.

Currently supported

Please refer to the list of all features. To check the feature support for each converter. It is possible that not every converter supports every feature. Only the intersection of the features of two EndpointConverters is used for the matching. Please keep that in mind regarding the equality of implementation and specification.


Setting up a test with hikaku is very simple. You just instantiate the Hikaku class and provide an EndpointConverter for the specification and another one for the implementation. Optionally, you can also pass an instance of HikakuConfig. Check the list of options and default values of the config. Then you call match() on the Hikaku class. The match result is sent to one or multiple Reporter. If the test fails kotlin's method is called.


There is an artifact for each converter. So we need one dependency for the specification and one for the implementation. In this example our project consists of an OpenAPI specification and a Spring implementation. The specification does not contain the /error endpoints created by spring, so we want to omit those. First add the dependencies for the converters, that we want to use. In this case hikaku-openapi and hikaku-spring.

dependencies {
    testImplementation: "de.codecentric.hikaku:hikaku-openapi:$hikakuVersion"
    testImplementation: "de.codecentric.hikaku:hikaku-spring:$hikakuVersion"


And now we can create the test case:

class SpecificationTest {

    lateinit var springContext: ApplicationContext

    fun `specification matches implementation`() {
                specification = OpenApiConverter(Paths.get("openapi.yaml")),
                implementation = SpringConverter(springContext),
                config = HikakuConfig(
                        ignorePaths = setOf(SpringConverter.IGNORE_ERROR_ENDPOINT)


Same example in Java:

public class SpecificationTest {

  private ApplicationContext springContext;

  public void specification_matches_implementation() {
    OpenApiConverter openApiConverter = new OpenApiConverter(Paths.get("openapi.json"));
    SpringConverter springConverter = new SpringConverter(springContext);

    HikakuConfig hikakuConfig = new HikakuConfig(
        new HashSet<>(Arrays.asList(SpringConverter.IGNORE_ERROR_ENDPOINT))
    new Hikaku(

More Info

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.