Background

Whilst developing with this plugin, I tried to use it, to deploy the api through a gitlab pipeline. Since there are multiple different potential clients, the issue was, that I required both json and yaml, for different usecases. Additionally I wanted to deploy the generated ui as a static html website as well.

The issue is, that I could only choose one specific, lead to a lot of frustrations for the client developers.

This major change allows to do that.

Removed Parameters

The following properties have been removed without deprecation:

apiDocsUrl
outputFileName

These two have been moved "exports".

Added Parameters

exports: a list of specific things to export from the api documentation
baseUrl: The base url to the api documentation (for example http://localhost:8080), reducing the boilerplate in exports.

Example usage:

<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.6</version>
    <executions>
        <execution>
            <phase>integration-test</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <baseUrl>http://localhost:8090</baseUrl>
        <exports>
            <export>
                <path>v3/api-docs.yaml</path>
                <outputFileName>openapi.yaml</outputFileName>
            </export>
            <export>
                <path>v3/api-docs.yaml</path>
                <outputFileName>ui/api-docs.yaml</outputFileName>
            </export>
            <export>
                <path>v3/api-docs</path>
                <outputFileName>openapi.json</outputFileName>
            </export>
            <export>
                <path>swagger-ui/index.html</path>
                <outputFileName>ui/index.html</outputFileName>
            </export>
            <export>
                <path>swagger-ui/swagger-ui.css</path>
                <outputFileName>ui/swagger-ui.css</outputFileName>
            </export>
            <export>
                <path>swagger-ui/index.css</path>
                <outputFileName>ui/index.css</outputFileName>
            </export>
            <export>
                <path>swagger-ui/favicon-32x32.png</path>
                <outputFileName>ui/favicon-32x32.png</outputFileName>
            </export>
            <export>
                <path>swagger-ui/favicon-16x16.png</path>
                <outputFileName>ui/favicon-16x16.png</outputFileName>
            </export>
            <export>
                <path>swagger-ui/swagger-ui-bundle.js</path>
                <outputFileName>ui/swagger-ui-bundle.js</outputFileName>
            </export>
            <export>
                <path>swagger-ui/swagger-ui-standalone-preset.js</path>
                <outputFileName>ui/swagger-ui-standalone-preset.js</outputFileName>
            </export>
            <export>
                <path>swagger-ui/swagger-initializer.js</path>
                <outputFileName>ui/swagger-initializer.js</outputFileName>
            </export>
        </exports>
        <skip>false</skip>
    </configuration>
</plugin>

This example would fetch multiple parts from the swagger api.

Risks

This is a breaking change. It is possible to make it not as breaking, but this would introduce a lot of complexity to maintain these legcy way.

Open Points:

Is the name "exports" okay? Naming is one of my weaknesses.
Would more "ease of use" functions be a good idea?
Any interactions I did not think about?
Is this a good Idea in general, or is this going against the idea of this framework and would require another plugin?

springdoc / springdoc-openapi-maven-plugin

Adjustments to allow multiple parallel fetches from the api #44