Search code examples
javamavenopenapimaven-plugin

OpenAPI equivilant of Jersey Jax-RS com.github.kongchen:swagger-maven-plugin?

In Swagger, you could use the swagger-maven-plugin to build the contract .json at compile time.

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.3</version>
    <configuration>
        <apiSources>
            <apiSource>
                <springmvc>false</springmvc>
                <locations>com.example.rest.resources</locations>
                <schemes>https</schemes>
                <info>
                    <title>project Service</title>
                    <version>v2</version>
                    <description>Description here.</description>
                    <contact>
                        <email>test@example.com</email>
                        <name>project Service</name>
                    </contact>
                </info>
                <outputPath>${basedir}/target/generated-resources/document.html</outputPath>
                <swaggerDirectory>${basedir}/target/generated-resources</swaggerDirectory>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Is there an equivalent way to Given a Jax-RS maven project, use a plugin create an OpenAPI client at maven build time using the current project's java source to generate a stubs?

I found a project out there that uses the integration-test phase to actually start the app using spring test runner then uses the http endpoint to build the contract.

I guess it works but it's not very convenient. The swagger one was way better it ran statically at compile time.

Solution

  • See https://github.com/springdoc/springdoc-openapi/issues/140

    Look at springdoc-openapi-maven-plugin which can help you generate the yml/json OpenAPI description during integeration test phase in maven.

    https://github.com/springdoc/springdoc-openapi-maven-plugin

    Note this does not do it at compile time. But it does it in the integration test phase when you have a running Spring server available.

    Does not seem to be a Maven plugin for this yet that I can find.

    You can very simply do this in Java.

    Assuming you have a Jax-RS application: YourResourceConfigurationWithOpenApi here is an example of how to write yaml without Spring boot application running:

    OpenApiContext ctx = new JaxrsOpenApiContextBuilder()
                    .application(new YourResourceConfigurationWithOpenApi())
                    .buildContext(true);
OpenAPI oas = ctx.read();
String res = ctx.getOutputYamlMapper().writer(new DefaultPrettyPrinter()).writeValueAsString(oas);
System.out.println(res);