Spike: Investigate creating OpenAPI YAML from our code

[cmbz]

Overview

The openapi endpoint provided by Payara results in an internal server error in version 6.0, as detailed here: #9981

Payara has been contacted for a fix (see: #9981 (comment)).

This spike proposes that while we await the Payara fix, we investigate using the OpenAPI Generator Tool to determine feasibility, as recommended here: #9981 (comment)

Related

• OpenAPI endpoint is broken #9981

[cmbz]

2024/01/17: Moved to sprint ready so work can start.

[pdurbin]

As I mentioned in standup, I'm going to change the title of this issue to make it more generic.

After poking at https://github.com/OpenAPITools/openapi-generator a bit and playing with the example at https://openapi-generator.tech/docs/plugins/ I'm not so sure that this is the right tool for generating the OpenAPI YAML we want. Instead, it seems like it produced client code from OpenAPI YAML.

I checked with @poikilotherm who suggested some additional libraries to try:

"I might have gotten that one wrong - the OpenAPI generator is about generating Java code from the spec, not the other way round

But: I did some digging, looking specifically for generating the OpenAPI YAML file... And here's what I found:

A) Use Swagger and Swagger Annotations. https://github.com/swagger-api/swagger-core/blob/master/modules/swagger-maven-plugin/README.md and https://github.com/openapi-tools/swagger-maven-plugin (not sure what the difference is). There is also https://github.com/stoicflame/enunciate which supports Swagger output as well as generating client code in a variety of languages.

B) Use MicroProfile OpenAPI annotations (these are the ones also useable with Payara /openapi endpoint) and use other plugins: https://geronimo.apache.org/microprofile/openapi.html or https://github.com/smallrye/smallrye-open-api/tree/main/tools/maven-plugin

I think the best shot is the SmallRye Maven Plugin, as it provides code scanning and keeps us compatible with the Payara OpenAPI implementation"

So next we should try some of the above.

[jp-tosca]

Testing this plugin I was able to generate the following spec:

openapi.json

I also generated the yaml version but GitHub doesn't allow them 😓

[pdurbin]

Here's, I grabbed the YAML from the post JP made and added .txt so GitHub will take it: openapi.yaml.txt

This is great! I guess if we go with this approach we should figure out where to put these files. It reminds me of how we put SchemaSpy output here, for example: https://guides.dataverse.org/en/5.14/schemaspy . That said, SchemaSpy has been treated as a one-off, something @donsizemore kindly does manually. Maybe this output should go directly into doc/sphinx-guides/source somewhere and get committed as part of a PR? It could even be useful for code review to see how the API has been extended or changed. And of course, we'd like to the output from the guides so API users can easily find it.

[pdurbin]

On a related note, I just built a version of Payara (for the first time) using the PR that fixes /openapi and left some notes about how I built it and where I put it: #9981 (comment)