Forum Discussion

SamuelMarks's avatar
Frequent Visitor
4 years ago

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:


/* */
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
$ref: '#/components/schemas/User'
summary: User Example
externalValue: ''



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?

No RepliesBe the first to reply