OpenAPI definitions for JS apps

[letmaik]

app.json allows to define an inlined OpenAPI Operation object per endpoint. This is currently ignored in CCF.

The aim of this issue is to determine whether the current approach (inlined Operation object) should be kept, and whether there are any implementation issues.

Inlining has the advantage of being self-contained, and hence not having to deal with sharing schemas between endpoints and dealing with naming conflicts in CCF when combining with built-in endpoints (gov/node).

There are a couple of downsides though, some just concerning end-user readability, others concerning losing of metadata:

1. As discovered in @Security decorator support for forum sample / tsoa apps #1824, OpenAPI requires security schemes to be defined in the top-level "components" section. Since those schemes cannot be inlined, they will be lost, essentially creating an invalid OpenAPI document, since the "security" fields of each operation will refer to names that are not defined: "Each name MUST correspond to a security scheme which is declared in the Security Schemes under the Components Object."
2. Same as above, Discriminator objects cannot be used when inlining as they require referencing schemas in components. This feature is useful to (in principle) short-cut validation and produce better error messages for union types. I don't think this feature is widely used and it doesn't hurt much if it gets stripped away. fwiw, tsoa doesn't emit/support it, although of course custom schemas can always be provided.
3. Inlining body schemas that are used by multiple endpoints, for example error responses, leads to a bigger OpenAPI doc and makes it less readable, since the meaningful schema names are lost. This is not the end of the world but if you were to generate API docs from it it wouldn't be pretty. Generating API clients from such OpenAPI docs (e.g. creating TypeScript interfaces) would also not be as nice, for the same reason.

[achamayou]

That seems addressed by #1874, @eddyashton @letmaik could you confirm?

[letmaik]

Well, addressed in the sense that we just went for the inline option. If it wasn't for point 1 I would close this issue. I guess we can handle this eventually at the framework level though, meaning we only officially support JWT or PKI auth and CCF would insert the relevant security scheme in the components section, and the idea is that apps must conform to that and refer to the same security scheme name in their inline OpenAPI definitions.

[achamayou]

Ok, so:

• CCF should expose a minimal components block, with the security schemes that it currently supports.
• app.json should support defining a common components block, which can be used to share common type definitions and in particular the values used for security fields.

[letmaik]

Let's start with the first point. The second point is more tricky as it's harder to integrate with tooling. The only use case related to security for the second point would be if the app defines a custom security scheme, which I think we don't have to support for now.

[achamayou]

It would also help readability, but agreed.

[achamayou]

Not going to add substantial new user APIs before container re-design.