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
A prototype created: gradle task, and some trial run on RS kotlin code where API functions live, exam the spec generated.
Check the manual annotation override to amend the API spec derived from bytecode
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