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?