[FEATURE] (type-safe-api) WebSocket API Documentation Generation

[cogwirrel]

Describe the feature

Support for generating documentation for WebSocket APIs.

Use Case

For parity with Type Safe API.

Proposed Solution

While we do have an OpenAPI spec, using the existing documentation generation will produce API docs which look too much like a REST API, for example will include HTTP methods and paths.

Either by modifying or wrapping existing generators, add support for generating documentation which shows each operation and it's input types. It would also be useful to include that the data sent on the websocket needs to be of the format { "route": "<Operation>", "payload": ... }.

Given that redoc produces the best documentation, it's worth investigating whether that can be customised at all.

It may be wise to add a new enum, WebSocketDocumentationFormat instead of reusing DocumentationFormat as we do currently, so as not to tie them together. This wouldn't be considered a breaking change as we throw an error at projen synth time if the user has provided any documentation formats.

Other Information

Remove the following once implemented:

aws-pdk/packages/type-safe-api/src/project/type-safe-websocket-api-project.ts

Lines 287 to 292 in a0dda50

	// TODO: Delete when documentation support is implemented
	if (documentationFormats.length > 0) {
	throw new Error(
	"Documentation generation is not yet supported for WebSocket APIs"
	);
	}

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

PDK version used

0.23.26

What languages will this feature affect?

No response

Environment details (OS name and version, etc.)

OSX

[cogwirrel]

May be worth considering converting the OpenAPI-like spec to AsyncAPI and then using the Async API CLI to generate documentation from that.