the processor

a quick example

The processor will only generate java interfaces describing the endpoints and the required model (POJOs) classes from an OpenAPI yaml document.

Let’s take a look at a very simple example. The following OpenAPI yaml describes a single endpoint. A call to the /ping endpoint will simply respond with a plain text string result.

openapi: 3.0.2
info:
    title: openapi-processor-spring sample
    version: 1.0.0

    paths:
      /ping:
        get:
          tags:
            - ping
          summary: returns a single "pong" string.
          description: very simple sample endpoint.
          responses:
            '200':
              description: pong
              content:
                text/plain:
                  schema:
                    type: string

Running the processor on this openapi yaml will create the following java interface:

package com.github.hauner.openapi.api;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;

public interface PingApi {

    @GetMapping(path = "/ping", produces = {"text/plain"})
    String getPing();

}

It is now up to you to implement the interface, e.g. like this:

package com.github.hauner.openapi;

import com.github.hauner.openapi.api.PingApi;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;

@RestController
public class PingController implements PingApi {

    @Override
    public String getPing () {
        return "pong";
    }

}

That’s it.

Of course the processor is capable of handling more interesting endpoint descriptions. The other sections provide some more detail about what is generated from which input.