SPIKE: Prototype Generating OpenAPI Spec with jooby openApi spec generator

[JFU-NAVA-PBC]

User Story

Swagger UI is popular as API documenting tool, the core of the API docs are the OpenAPI spec, could be in json / yaml format, the usual approach is using swagger annotations to "document" the API methods (endpoints) in the source files: java / kotlin / python / etc.

We have a ticket doing it in that conventional manner:

Annotate the source code and then run the generator to obtain the spec

However, the work of annotating the source code with swagger annotations is not trivial, some times, the annotations take more lines than the actual function / methods

Jooby (https://jooby.io/) offers a bytecode analysis based generator which (to be verified and evaluated for actual usability) does not require manual annotation of the code while still support annotation processing as an override,

Think it might be worth a prototyping to see if it can generate usable API docs and use less labor.

Description/Use Case

Use case: generating OpenAPI spec from kotlin source code for RS APIs (endpoints)

Risks/Impacts/Considerations

No risk, it is aimed to improve on existing approach we already have

Dev Notes

Need a prototype to see how good the the spec generated

Acceptance Criteria

1. A prototype created: gradle task, and some trial run on RS kotlin code where API functions live, exam the spec generated.
2. Check the manual annotation override to amend the API spec derived from bytecode

[bishoyayoub]

@JFU-NAVA-PBC Please confirm that this is ready for grooming.

[JFU-NAVA-PBC]

@bishoyayoub yes

[bishoyayoub]

@arnejduranovic do you know which epic this belongs to?