Docs: Add advisory for JSON Pointer errors in OpenAPI specs

Docs: Add advisory for JSON Pointer errors in OpenAPI specs

Add documentation advisory explaining the JSON Pointer resolution
failure caused by forward slash (/) characters in Swagger 2.0
definition key names.

When migrating from the deprecated swaggerv2doc directive to the
openapi directive, auto-generated Swagger specs from OpenDaylight
YANG tooling contain definition names like:

  ASDC-API/artifacts(config)artifact

The / character is the JSON Pointer path separator (RFC 6901), so
jsonschema incorrectly interprets these as nested paths rather than
flat keys under definitions, resulting in:

  _RefResolutionError: Unresolvable JSON pointer

The advisory documents two fix approaches:
  Option A (recommended): Rename keys, replacing / with .
  Option B: Use RFC 6901 tilde escaping (~1) in $ref values

Also adds a cross-reference from the existing api-swagger-guide.

Ref: https://gerrit.onap.org/r/c/ccsdk/distribution/+/143029
Issue-ID: CIMAN-33
Change-Id: I201a82e8de14e3cba5ae4abbfaf88748710341a8
Signed-off-by: Matthew Watkins <mwatkins@linuxfoundation.org>