OpenAPI in function docstring? - YAML verbatim vs JavaDoc #2459

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:

/* */
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:

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?