Generate Wiremock specification from OpenAPI specification

[mcruzdev]

Introduction

Hi everyone, I want to share an old idea here.

I talked with @hbelmiro one time about this idea for helping in contract testing and integration tests, but I decided to propose this idea later because I am new in the project and I went to learn more about. I saw today that there is an extension called quarkus-wiremock and this idea can help both projects.

Propose

The idea is to generate Wiremock specification from OpenAPI specifications. Finding through the internet I just found two ways to do it, the first one is using Wiremock Cloud (paid) and using a CLI writen in Javascript called Prism is necessary to install NodeJS and the integration could be hard.

There is no way to it with another way (I could be wrong).

Features

• Generate wiremock specifications for CI pipelines.
• Generate wiremock specifications to work together quarkus-wiremock extension.

Given a OpenAPI spec:

openapi: 3.0.0
info:
  title: Exemplo de API
  version: 1.0.0
  description: OpenAPI to Wiremock
paths:
  /some/thing:
    get:
      summary: Something endpoint
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
              example: "Hello, world!"
          headers:
            Content-Type:
              schema:
                type: string
              example: "text/plain"

Generate an Wiremock stub:

{
  "request": {
    "method": "GET",
    "url": "/some/thing"
  },

  "response": {
    "status": 200,
    "body": "Hello, world!",
    "headers": {
        "Content-Type": "text/plain"
    }
  }
}

What do you think? @gastaldi @hbelmiro @ricardozanini

[hbelmiro]

Sounds good to me.
More context about it: https://docs.wiremock.io/swagger/

Questions:

1. Does Quarkus code generator support test classes, otherwise we'll have to mix two code generators.
2. @carlesarnal, just to be sure, this feature is not part of your PR to add server code generation, right (I still didn't have time to review it)?

[mcruzdev]

I saw that pull request #482 uses Wiremock only on test packages. Now, about Apicurio, IMHO I think the server generator will generate only server code (obvious haha) like Resource, etc. I need to study more about Apicurio and their integrations with Wiremock or stubs (check the possibility) on test environment.

[ricardozanini]

@hbelmiro not sure if the generator supports test classes, I believe it does. We can ask on Zulip.

+1 for generating those stubs, but on a separate module/extension. Is that the proposal?

[ricardozanini]

Open a PR :)

[hbelmiro]

@mcruzdev this PR must be synced with #482 since both will change the module structure.
I think the easiest way is just to wait for #482 to be merged.
You also can base your branch on top of https://github.com/carlesarnal/quarkus-openapi-generator/tree/add-server-extension in the meantime, if you want to start working on this now, and once #482 gets merged you can rebase your PR on top of main.

Also, this feature must be merged after we drop support for Quarkus 2.

[mcruzdev]

I will work on designing the API first, and I will wait by the pull request mentioned.

[mcruzdev]

Hi @hbelmiro @ricardozanini designing the proposal, I stopped into how strategy we will get to select the right response from OpenAPI, I looked it https://docs.wiremock.io/openapi/, I think that we can follow the same Stub generation rules. https://docs.wiremock.io/openapi/#Stubs%20generation%20rules

[hbelmiro]

@mcruzdev I agree with following the same strategy as WireMock.

[mcruzdev]

RFC: OpenAPI to Wiremock

Status: In Progress

Objective

The objective of this proposal is to establish a method for converting OpenAPI specifications into Wiremock stubs,
either as Java code or in JSON format, within the Java/Quarkus ecosystem.

Motivation

Presently, there lacks a straightforward approach to translate an OpenAPI specification into Wiremock stubs (in either
Java code or JSON) within the Java ecosystem.

For Quarkus users aiming to develop integration tests, the process involves a considerable time investment or an
expense (such as utilizing Wiremock Cloud) to generate Wiremock stubs. While there exists an excellent Quarkus extension
named quarkus-wiremock, it currently lacks the capability to generate
these stub tests out-of-the-box.

User Benefit

The proposed solution aims to provide Quarkus users with a streamlined process for generating Wiremock stubs dire

Design Proposal

The proposal initially suggests providing the client with only two methods:

Initial interface

The proposal is initially give to the client only two methods:

interface OpenApiWiremock {
    String generate(final String openApiSpec);
    String generate(final String openApiSpec, final OutputMode outputMode);
}

Initially we will only supports JSON Wiremock stubs.

If the client sets OutputMode.JAVA_STUB, they will receive the following Java code based into OpenAPI specification.

public class QuarkusOpenApiWiremockStubs {
/** ... */
}

If the user sets OutputMode.JSON_STUB, they will receive the following JSON:

{
  "mappings": [
    {
      "request": {
        "method": "GET",
        "url": "/applications"
      },
      "response": {
        "status": 200,
        "body": "Hello from Quarkus"
      }
    }
  ]
}

Strategy to Selecting the appropriate Wiremock Stubs

First, we need to know that the library will respect the Content Negotiation, it means that we will add to
stub Accept ({path}.{method}.responses.{status}.content.{mediaType})
and Content-Type ({path}.{method}.requestBody.content.{mediaType}) headers.

It will serve to differentiate multiples Stubs, if the Media Type is not valid the library will ignore the PathItem.

IMPORTANT Initially we will no work with $ref objects.

Stub generation will be based on the following rules with descending priorities:

1. 2xx request with example in parameters and example in responses.

      parameters:
        - name: appName
          in: query
          schema:
            type: string
            example: 62e61768-90bb-11ee-b9d1-0242ac120002
      responses:
        "200":
          description: Get
          content:
            "application/json":
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The Application ID
                    example: 62e61768-90bb-11ee-b9d1-0242ac120002
                  name:
                    type: string
                    description: The Application Name
                    example: Platform Core Application

In this case the stub will be:

public class QuarkusOpenApiWiremockStubs {

    private static final String QUARKUS_APPLICATIONS_APP_ID_GET_RESPONSE = "{ \"id\": \"62e61768-90bb-11ee-b9d1-0242ac120002\", \"name\": \"Platform Core Application\"}";

    public static final MappingBuilder QUARKUS_APPLICATIONS_APP_ID_GET = WireMock.get(WireMock.urlEqualTo("/applications/62e61768-90bb-11ee-b9d1-0242ac120002"))
            .willReturn(aResponse().withStatus(200).withBody(QUARKUS_APPLICATIONS_APP_ID_GET_RESPONSE));
}

• If no example is set and there is at least one item in the examples, it will randomly select only one.
• If no example is set and there is no examples items, it will autogenerate a response/parameters/requestBody based on schema type.
• If there are 200 and 201 status code, the 200 will have the precedence.

GET

{
  "responses": {
    "200": {
      "description": "Successful operation",
      "content": {
        "application/xml": {
          "schema": {
            "$ref": "#/components/schemas/Pet"
          }
        },
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Pet"
          }
        }
      }
    },
    "400": {
      "description": "Invalid ID supplied"
    },
    "404": {
      "description": "Pet not found"
    },
    "405": {
      "description": "Validation exception"
    }
  }
}

Having in mind that the user wants to

[mcruzdev]

H @hbelmiro @ricardozanini The WireMock for Java was delivered 4 days ago, se here: OpenAPITools/openapi-generator@092463a

😢

[ricardozanini]

@mcruzdev I think we can then review this issue/discussion to upgrade the inner generator and verify if it works. If so, we add a note in our docs. 👍

[mcruzdev]

@ricardozanini Did you mean to use the generator from OpenAPITools instead of creating the template with Qute?

[ricardozanini]

Same thing we did about generating the models. We replaced the template engine. :)

[mcruzdev]

@ricardozanini and @hbelmiro
The idea here is to create another module, right? Or we will change to add the wiremock stuff in the existing module?

[ricardozanini]

Another module preferably, yes! We rule out wiremock from the default and also we can freely change the engine the way we want there.