Open API [swagger] is a fancy way of writing REST API documentation, it looks like:

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

A huge number of REST API micro-frameworks are written with a simple function or class, that look something like:

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();

Now the question is what to put in the /* */. I've seen many approaches which just put the YAML verbatim as the new docstring. Is that the recommended approach, or is there a way to coerce it into a language-specific—JavaDoc, ReST, &etc.—docstring?

(writing bidirectional code-generators, to/fro OpenAPI and various programming languages)

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.