Add Swagger/OpenAPI to docstring: YAML, JSON, or JavaDoc style?

Writing bidirectional code-generators for a number of languages, that take the language and generate Swagger/OpenAPI, and take Swagger/OpenAPI and update—or insert—the target language.

My question is what to put in the docstring, for example this pseudocode route:

```javascript

/* */
async function create_user(request, response) {
try {
const created_user = await db.create(User, request.json);
} catch (e: ValidationError | DatabaseError) {
response.status = 400;
return e.json();
}
response.status = 201;
return created_user.json();
}
```

What should the docstring say? - I've seen some approaches which just put YAML verbatim inside, like:

```yaml

description: user to add to the system
content:
'application/json':
schema:
$ref: '#/components/schemas/User'
examples:
user:
summary: User Example
externalValue: 'http://foo.bar/examples/user-example.json'

```

But that seems rather nonstandard for maintainers. They need to think about the OpenAPI specification rather than JavaDoc (or whatever docstring format their language recommends). Is there a compromise, a way of specifying inside the docstring? - Or would you suggest just to use your YAML?