OpenAPI in function docstring? - YAML verbatim vs JavaDoc

[SamuelMarks]

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?

[MikeRalphson]

I've converted this issue to a discussion item, as it doesn't represent an issue or idea for the specification itself. Hopefully members of the community with experience of code annotations will add their thoughts here.

[SamuelMarks]

Oh I didn't realise discussions are a thing now. Good work Microsoft!

[handrews]

@SamuelMarks with apologies for the back-and-forth (we're kind of coming out of pandemic-era hibernation, and no one currently active seems to recall what the plan was for discussions vs issues), I'm going to close this in favor of issue #1740 which tracks the specification aspects. But I also encourage looking at the OAS 4 "Moonwalk" discussions which are in their own repo.

As for the "what should I do with docstrings" part, that's outside of the scope of the specification, and our set of active volunteers isn't large enough to curate non-specification discussions. You might find some fellow implementors on our Slack. More people monitor that than monitor these discussions.

[SamuelMarks]

Thanks yeah it's a curious problem but I thought others would be interested in. Maybe the OpenAPI 4 discussion is the right place (as you linked).

Some annoyances around whitespace, but the more specific thing is about how to represent expectations/constraints/exceptions in a language-specific rather than your DSL-only (OpenAPI's language as represented by, say, YAML).