How to escape angle brackets in YAML?

Question

OAS:

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
servers:
  - url: http://localhost:8080/api
paths:

  /users:
    get:
      summary: "Find all existing users"
      operationId: findAll
      responses:
        '200':
          description: "Users found. Response: List<User>"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    ...

Checking SwaggerUI, I noticed the description is just

Users found. Response: List

when it should be

Users found. Response: List<User>

How do I escape the angle brackets?

Answer 1

OpenAPI allows for Markdown in the description field. Relevant part of the specification:

Throughout the specification description fields are noted as supporting CommonMark markdown formatting. Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.

Markdown allows for inline HTML tags, as described in the CommonMark spec:

Text between < and > that looks like an HTML tag is parsed as a raw HTML tag and will be rendered in HTML without escaping. Tag and attribute names are not limited to current HTML tags, so custom tags (and even, say, DocBook tags) may be used.

<User> looks like an inline HTML tag. Therefore when showing the description, it is not rendered as text, but ignored because it's an invalid HTML tag.

The solution is to write List<User>.