configuring openapi-processor-maven

what is openapi-processor?

openapi-processor is a small framework to process OpenAPI yaml files. Currently, openapi-processor provides java code generation for Spring Boot and conversion to json.

It does support gradle and maven to run any openapi-processor as part of the build process.

See the documentation for more. There is also a playground to preview the processors.

The maven plugin is the newest member of the openapi-processor family, and the following sections provide a short introduction into its configuration.

introduction

I will just show the configuration of the maven plugin for integrating an OpenAPI yaml file. I don't describe the creation of a Spring Boot application.

Integrating it in a new Spring Boot starter project created by Spring Initializr (maven & web-mvc) should work without issues.

To see a working demo project take a look at the openapi-processor samples. The available samples have a pom.xml, and a build.gradle file, so you can build them using maven or gradle.

what to expect

Assuming a (simple) OpenAPI yaml file:

openapi: 3.0.2
    info:
      title: ping api
      version: 1.0.0

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

the openapi-processor-maven plugin will generate a java interface by running the openapi-processor-spring (in short oap-spring).

The interface generated for the simple api will look like this (the package name io.openapiprocessor.simple is configurable):

package io.openapiprocessor.simple.api;

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

public interface PingApi {

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

}

You can now implement the interface to provide a working endpoint in your Spring Boot application.

The sample implements the interface with a hardcoded result like this:

package io.openapiprocessor.simple;

import  io.openapiprocessor.simple.api.PingApi;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;

@RestController
public class PingController implements PingApi {

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

}

Now let's look at the necessary configuration to generate the interface from maven.

Continue reading here.

Originally published at https://hauner.github.io on July 18, 2020.