So use any of a dozen or so other configuration formats that have comments but don't have all the problems YAML does. TOML is probably the most popular of those right now.
Also, OpenAPI specs (also known colloquially as Swagger) can only be written in JSON or YAML.
To note, JSON specifically doesn’t have comments to close the door to annotations and other kind of meta use.
In the cases where you have a tool that require json or yaml, you could use something like cue, dhall, or jsonnet, and convert it into json (or yaml). Unfortunately, that's a little tricky when your build cinfiguration itself has to be in yaml, as is the case for github actions, travis-ci, etc.