Contribute OpenAPI spec pieces from extensions

[jannyHou]

Suggestion

This is inspired by spike. Authentication strategies should be able to contribute security schemas and operation security config into the app's openapi spec.

Let's start from creating an extension point for adding OpenAPI specs. It will read specs from extensions. Like ControllerSpecBuilder generates the operation specs, AuthenticationSpecBuilder reads security specs from all registered auth strategies(here it means register to another extension point for auth strategy).

And the rest server will load all registered OpenAPI spec pieces and merge them together.

Use Cases

When people want to contribute OpenAPI spec pieces, they can register an extension that provides the spec.

A proposal:

start with app.api spec.
get controller to add operation spec
then pass the resulting open api spec to extensions of the extensionPoint to contribute

Contract for the extension point

transform( openApiSpec) : ValueOrPromise

Then the extension point has a loader to find all extensions and call extensionName.merge() to keep adding more specs.

Examples

E.g. ControllerSpecBuilder generates the operation specs. AuthenticationSpecBuilder reads security specs from all registered auth strategies(here it means register to another extension point for auth strategy).

Acceptance criteria

• Create an extension point for contributing OpenAPI spec
• Tests
• Documents

[jannyHou]

cc @raymondfeng @emonddr I created this task as we discussed in the estimation meeting. Feel free to edit the description. Thanks.

[dhmlau]

@jannyHou, assigning this to you per our discussion with you and @emonddr.

[emonddr]

@jannyHou , on this pass, are we really going deliver AuthenticationSpecBuilder ? Or is the ControllerSpecBuilder sufficient for now, and in 2020 we deal with AuthenticationSpecBuilder?

[jannyHou]

Close after PR merged