Openapi yaml

[mooreds]

This is a first pass at generating an openAPI yaml file from the API and domain JSON files.

This deploys files to the https://github.com/FusionAuth/fusionauth-openapi repository, where it can be versioned and released like any other client library package (not quite sure how the release plugin works, so I just copy pastaed it).

There are some flaws in the implementation. While the specification is valid, the generated client libraries haven't been fully exercised.

In particular:

• polymorphic operations are not well supported by the client library generators. That means that identity provider requests and responses are not functional. I'm not sure if there are workarounds, but it seems like some work is being done. See [Java] Swagger oneOf type: Jackson trying to instantiate interface instead of implementation? swagger-api/swagger-codegen#10011 for example.
• this file is generated from the fusionauth-client-builder JSON files, not from code. This means that there may be gaps when compared to the REST API.
• there's no information about what parameters are required or not, because that is not part of the API JSON files.
• there are certain operations, status codes and security mechanisms (JWT auth, cookies for auth) that are not currently supported, again, because they are not included in the API JSON files.
• oauth specific operations are not currently supported

Rollout plan:

• Review with eng team, determine if current state is shippable to alpha users.
• Ask folks who commented on Investigate OpenAPI for documentation and client library generation fusionauth-issues#614 or otherwise expressed interest in this to kick the tires.
• Determine what features need to be added to ship.
• Fix any outstanding issues/add features.
• Publish as 'tech preview' in docs. Close bugs for other SDKs.
• Let it burn in for a few months, fix any issues.
• Start publishing it as part of the release process. Maybe include it in the build? Maybe just on the download page.
• Go back and provide specs for previous releases so that folks can use apidiff functionality.
• Investigate bringing things closer to the code/fusionauth-app so that we don't need to maintain the API JSON files.

[voidmain]

It's a lot of code to digest, but the first thing that jumped out was that the instants don't look to be correctly handled. We use integers for all instants (ZonedDateTime) and they represent the number of milliseconds since Epoch.

[mooreds]

Okay, let me take another pass and re-request code review.

[voidmain]

Let's do this!