Convert API keys functions to use annotations to generate api docs

[mkalish]

User Story:

As a consumer of the report stream API, I want the documentation of the public key endpoints to be automatically kept in sync with the code

Description/Use Case

All the endpoints in ApiKeyFunctions are documented automatically, instead of having to manually update the .yml files in prime-router/docs/api

Risks/Impacts/Considerations

Dev Notes:

Should be able to start from this PR and document the rest of the end points

Acceptance Criteria

• [ ] an api.yml function is generated when the code is built
• [ ] all the functions in ApiKeyFunctions is documented via annotations

[bishoyayoub]

Hey team! Please add your planning poker estimate with Zenhub @arnejduranovic @luis-pabon-tf @JessicaWNava @jack-h-wang @jimmyfagan @mkalish

[JFU-NAVA-PBC]

paired with Michael and adopted a previous PR (look good - a decent solution)

hit error (see below) when commit the PR, might be that my git hub account has not been provisioned with write permission, will check with team next work day:

OK> pre-commit hooks passed! error: gpg failed to sign the data fatal: failed to write commit object

[JFU-NAVA-PBC]

jooby.io seems offer gradle, java, kotlin included openAPI spec generation from kotlin / java code, and it parses the bytecode to generate open API spec, see quote below:

"This module helps automating the generation of API documentation using Jooby projects. jooby-openapi works by examining an application at build time to infer API semantics based on byte code and optional annotations.

So it derives API spec from bytecode - no need to annotate the source code, and it also support annotation - if present annotation will override the bytecode parsing.

I'll create a ticket (SPIKE), to prototype with jooby generator, but this is not urgent since Michael's PR meets the AC already.

[JFU-NAVA-PBC]

added more annotations to the ApiKeysFunction.kt

FYI:

Created a SPIKE (prototyping) ticket for jooby.io spec generator (annotationless bytecode based API spec gen)

10104

[JFU-NAVA-PBC]

Some discussion about next steps:

Quote from PR review conversations:

We should run this automatically as part of the build process, Instead of having to do it manually. Should we be committing these files to the repo? My vote would be no, so maybe we should put these in the build directory? If we are going to host docs eventually, where is the best place to put them?

The place RS API docs are served:

RS staging instance - is it public? is it behind an Akamai gateway? if so our staging is a good place to host the swager UI for RS APIs - can use swagger UI dist and modified with RS yaml files associated with the swagger initializer JS.

If staging is not public - e.g. has to be on CDC vpc, then I suggest a sandbox instance.

PROD env is not a good place to host a live swagger UI API docs, to avoid security risk (CORS etc) and interference with PROD traffic.

webUI where the APIDocs link shown: we can leverage engagement's front end, make it a Report Stream portal among other functions.

Just some thoughts for down the road.

[JFU-NAVA-PBC]

FYI,

Per Arnej's PR review, we can proceed to try to deploy the partial API docs to at least staging to see how it works.

Not sure if I have been provisioned with deploy to staging permission yet??

I created a ticket to track that: #10262

cc: @bishoyayoub @arnejduranovic