Fix generation of openapi spec document

[planetf1]

In server-chassis-spring we have an optional profile which allows building an openapi spec document which can then be served elsewhere

This was created using

mvn -Dopenapi clean install

However this is now broken, failing with:

org.springframework.context.ApplicationContextException: Failed to start bean 'webServerStartStop'; nested exception is org.springframework.boot.web.server.WebServerException: Unable to start embedded Tomcat server
.....
Caused by: java.io.FileNotFoundException: /Users/jonesn/IdeaProjects/egeria.maven/open-metadata-implementation/server-chassis/server-chassis-spring/truststore.p12 (No such file or directory)

I propose to
a) Fix this failure
b) Always generate the openapi spec (if performance is appropriate)
c) Update build script to save the document as a build attachment

for both maven and gradle

I will add to the assembly at this time
cc: @mandy-chessell

[planetf1]

Initial attempt at fixing this involved updates to the server-chassis-spring pom.xml

First we can change ensure the truststore is passed when launching the server. ie in the 'pre-integration-test' execution of the spring boot maven plugin we add:

                  <plugin>
                        <groupId>org.springframework.boot</groupId>
                        <artifactId>spring-boot-maven-plugin</artifactId>
                        <executions>
                            <execution>
                                <id>pre-integration-test</id>
                                <goals>
                                    <goal>start</goal>
                                </goals>
                                <configuration>
                                    <jvmArguments>-Dstrict.ssl=false -Djavax.net.ssl.trustStore=${project.build.outputDirectory}/classes/truststore.p12 -Dserver.ssl.trust-store=${project.build.directory}/classes/truststore.p12 -Dserver.port=12864</jvmArguments>
                                </configuration>
                            </execution>
                            <execution>
                                <id>post-integration-test</id>
                                <goals>
                                    <goal>stop</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>

We also need to update the URL for the 'generate' goal of the springdoc-openapi-maven-plugin. Whilst we are at it, set all the output parms for clarity ie:

                  <plugin>
                        <groupId>org.springdoc</groupId>
                        <artifactId>springdoc-openapi-maven-plugin</artifactId>
                        <executions>
                            <execution>
                                <id>integration-test</id>
                                <goals>
                                    <goal>generate</goal>
                                </goals>
                                <configuration>
                                    <attachArtifact>true</attachArtifact>
                                    <outputFileName>server-chassis-api.json</outputFileName>
                                    <outputDir>${project.build.directory}</outputDir>
                                    <apiDocsUrl>https://localhost:12864/v3/api-docs</apiDocsUrl>
                                </configuration>
                            </execution>
                        </executions>
                    </plugin>

However with this done, the generation still fails since now the client (the openapi-maven-plugin) doesn't have truststore specified. Furthermore, this plugin offers no way to specify JVM options in order to pass it.

Potentially the server could be run with http, but this needs a modification to the server to add back http support. This seems an undesirable step.

The overall maven command could use the -Djavax.xxxxxx parms, but this only works where the user remembers & otherwise would fail - not very robust

Trying to generate the docs from the server running in the same way we do FVTs doesn't work either - as it's still the client at fault.

The GRADLE plugin for this DOES offer a way to specify the jvm parms - see https://github.com/springdoc/springdoc-openapi-gradle-plugin (see 'forkProperties')

I have opened up an issue on the maven plugin at springdoc/springdoc-openapi-maven-plugin#28

Since we are in the process of migrating to gradle in any case, it may be that we only implement this for the gradle build

[planetf1]

• Add notes to run manually

[planetf1]

Further work done in my 5472 branch - however I'm still getting tricky cert issues which are tricky to resolve without more flexibility in the plugin.

Now going to look at the gradle approach instead.

[planetf1]

@mandy-chessell I've not yet had a chance to fix up either the maven or gradle build for this.

If you want to extract the openapi spec doc, just run the appropriate server chassis then issue a call:

curl  -k https://serverhostname:9443/v3/api-docs > /tmp/openapi.json

You can then import this file into an openapi editor, ie https://editor.swagger.io (which of course uses the same rendering we build into egeria, which causes issues ....)

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 20 days if no further activity occurs. Thank you for your contributions.

[planetf1]

removing maven tag, as will address this only for gradle