API reference documentation should also include enumeration descriptions

[liorokman]

Description:

The API reference documentation generated from the CRD structures currently doesn't include the valid values for Enum types.

For example, the ClientTrafficPolicy API contains an enum field called escapedSlashesAction of a type called PathEscapedSlashAction. The generated documentation doesn't list the set of valid values for this field.

Ideally, that information should be included in the generated documentation. For this example, the information is available and the following table could have been automatically generated:

Value	Description
KeepUnchanged	KeepUnchangedAction keeps escaped slashes as they arrive without changes
RejectRequest	RejectRequestAction rejects client requests containing escaped slashes with a 400 status. gRPC requests will be rejected with the INTERNAL (13) error code. The "httpN.downstream_rq_failed_path_normalization" counter is incremented for each rejected request.
UnescapeAndRedirect	UnescapeAndRedirect unescapes %2F and %5C sequences and redirects to the new path if these sequences were present. Redirect occurs after path normalization and merge slashes transformations if they were configured. gRPC requests will be rejected with the INTERNAL (13) error code. This option minimizes possibility of path confusion exploits by forcing request with unescaped slashes to traverse all parties: downstream client, intermediate proxies, Envoy and upstream server. The “httpN.downstream_rq_redirected_with_normalized_path” counter is incremented for each redirected request.
UnescapeAndForward	UnescapeAndForward unescapes %2F and %5C sequences and forwards the request. Note: this option should not be enabled if intermediaries perform path based access control as it may lead to path confusion vulnerabilities.

[liorokman]

I've opened a PR for the crd-ref-docs tool to support generating this sort of table: elastic/crd-ref-docs#79 .

Once it's merged, we can update the templates that EG uses to also generate this sort of table.