Discussion on: How to Document an Express API with Swagger UI and JSDoc

[Mamta Shettigar]

Hi I'm using swagger-jsdoc library. Wanted to know if Visual Studio code offers any extensions for intellisense? There is an extension named swagger-jsdoc but the syntax for post request is quite outdated according to openapi 3.0.0 and hence not able to get automatic intellisense for requestBody..It still uses ;-
parameters:

• - name: "param_name"
• description: "매개변수"
• in: body
• required: true
• type: string
• example: "foo"

Instead of requestBody:

• required: true
• content:
• application/json:
• schema:
• $ref: '#/components/schemas/NewUser'

[Alexander]

This is the main drawback of the whole swagger-jsdoc approach to swagger.
Defining API schema as an annotation to your method in the comment section is prone to typos and other mistakes that are not picked up.

I usually go to editor.swagger.io and define the whole API spec there with all the "definitions" schemas and what not. Alternatively, you could use the OpenAPI (Swagger) Editor extension for VS Code ( I don't use it though, so not sure how up-to-date it is).
Then it is a matter of copying pieces of it into right places in the code.
Also, note that you don't have to define the common definitions and schemas in the annotation section in your code. It is cleaner to put them into a separate yaml file, say definitions.yaml, then load the file directly into swaggerJSDoc object:

const options = {
  swaggerDefinition,
  // Paths to files containing OpenAPI definitions
  apis: ['./routes/*.js', './doc/definitions.yaml'],
};

[burloiumarian23]

Good hint ... it wasn't working initially for me , because I also added anotation paths which was wrong