Investigate OpenAPI for documentation and client library generation

[mooreds]

Investigate OpenAPI for documentation and client library generation

Right now FusionAuth uses https://github.com/FusionAuth/fusionauth-client-builder for building the clients and docs. This works and we have numerous client libraries.

However, there's a specification out there that may be worth evaluating -- OpenAPI (formerly swagger):

• https://swagger.io/docs/specification/about/
• https://www.openapis.org/

It might allow FusionAuth to accelerate the rate of new languages with client libraries by switching to OpenAPI. It might also promote more community involvement in our client libraries.

Things to consider as part of this evaluation:

• Does OpenAPI introduces a lot of unnecessary dependencies to client libraries (for example, does the Java client library that OpenAPI generates use Apache Commons or Spring)?
• Is OpenAPI capable of producing Java code that seamlessly integrates with the core codebase since we use our own Java Client for everything?

Requested Client Libraries

We may easily be able to deliver these additional libraries with OpenAPI.

• https://github.com/FusionAuth/fusionauth-issues/issues/603
• https://github.com/FusionAuth/fusionauth-issues/issues/974
• https://github.com/FusionAuth/fusionauth-issues/issues/1038

How to vote

If you have comments regarding OpenAPI and FusionAuth or would like to get this on our roadmap to consider, please comment and upvote the feature request.

[mooreds]

This has been mentioned before: https://github.com/FusionAuth/fusionauth-issues/issues/50

[voidmain]

Just so we don't forget: we'll need to evaluate how to parse the Java domain objects and spit out OpenAPI domain definitions.

[robotdan]

We can likely tweak our Java-2-JSON library to build the DSL expected by OpenAPI. Perhaps we should open source it. https://github.com/inversoft/java2json

[robotdan]

Related https://github.com/FusionAuth/fusionauth-client-builder/issues/19

[mooreds]

Also worth looking at if/when this is implemented: https://github.com/Endava/cats

[mooreds]

Interesting links/discussion here: https://news.ycombinator.com/item?id=26575455

[koshkarov]

We'd love to have OpenAPI spec, as it will allow us to easily test, generate client, etc. Please consider using it, that'd be super helpful.

[mooreds]

@koshkarov thanks for your feedback; please upvote the issue as that is how we measure community feedback when planning.

[pendenga]

I upvoted this, but also like to mention my use case. I've been doing a lot of debugging and support directly in the API using Postman. Postman can build the collection automatically given an OpenAPI spec, so that's my interest. I have my own collection I've been putting together as I go along, but it'd be nice to have one built from a definitive spec.

[mooreds]

Hi folks, we have experimental openapi support that I just released.

Here's the github repo: https://github.com/fusionauth/fusionauth-openapi with the spec and a readme with known issues.

It's also available via the https://fusionauth.io/docs/v1/tech/client-libraries/openapi/

Please pull down the openapi doc (only for 1.32.1 right now) and give it a whirl. Would welcome feedback about:

• how it works for you
• suggestions to make it better
• any bugs/issues you encounter

I'm going to leave this issue open for a while for comments. Would love to hear from @koshkarov @pendenga and anyone else who voted.

[mooreds]

More on openapi/link fest:

• https://news.ycombinator.com/item?id=27081084 has information and feedback on smithy and different openapi solutions
• Here's smithy: https://awslabs.github.io/smithy/2.0/index.html right now it looks nascent (no real client library support)
• Vendors who can build sdks for us: https://stainlessapi.com/ and https://www.speakeasyapi.dev/ (neither support all our target client libraries
• HN discussion on openapi: https://news.ycombinator.com/item?id=33220552
• Recommended alternative golang generator: https://github.com/deepmap/oapi-codegen