Contributions
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: ```javascript /* */ 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: ```yaml 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?548Views1like0Comments