swagger-jsdoc

It is important to note that swagger-jsdoc does not parse or interact with your actual application source code. It only reads JSDoc comments and pure YAML files to generate the OpenAPI specification. It does not perform any reading, parsing, or modification of your logic files.

If your workflow requires a tool that analyzes your source code (e.g., TypeScript interfaces or decorators) to generate specifications, consider using an alternative like tsoa.

It is important to distinguish between documentation and implementation. swagger-jsdoc is a documentation generator that works based on code annotations or static YAML files.

It does NOT:

• Add logic or implementation to your API.
• Validate the correctness of your underlying business logic.
• Fix errors in how your API behaves at runtime.

If you encounter errors or unexpected data when testing your API via Swagger UI, the issue lies within your application's implementation or the accuracy of your YAML descriptions, not within the swagger-jsdoc library itself.

Use swagger-jsdoc to integrate Swagger/OpenAPI documentation directly into your source code using JSDoc comments.

By adding @swagger or @openapi annotations above your API-related code, you can describe your API using YAML syntax. The library parses these annotations (and optionally external YAML files) to output a single, unified specification file. This allows you to document living code and feed the resulting specification into other Swagger tools.

Key Workflow:

1. Annotate code with @swagger or @openapi followed by YAML.
2. (Optional) Provide paths to external YAML files.
3. Run swagger-jsdoc to generate the final specification file.

When configuring the apis option, swagger-jsdoc uses node glob to discover files.

• Use patterns like *.js to select all JavaScript files in the current directory.
• Use patterns like **/*.js to select all JavaScript files in sub-folders recursively.

Note: All paths provided in the apis array are relative to the current working directory.

const options = {
  swaggerDefinition,
  apis: ['./src/routes*.js'], // Example glob pattern
};

To include API documentation in your source code, place the @swagger or @openapi JSDoc tag above your code. The content following the tag must be a YAML-formatted specification part. This is commonly used directly above route handlers in frameworks like Express.

/**
 * @swagger
 *
 * /login:
 *   post:
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: username
 *         in: formData
 *         required: true
 *         type: string
 *       - name: password
 *         in: formData
 *         required: true
 *         type: string
 */
app.post('/login', (req, res) => {
  // Your implementation comes here ...
});

The swagger-jsdoc CLI is a thin wrapper around the Node API. You can run it directly if installed globally, or via your package manager.

To use it via yarn:

yarn swagger-jsdoc

To view the help menu and all available options:

swagger-jsdoc -h

Use the CLI to generate an OpenAPI/Swagger specification by providing a definition file and one or more input files containing your documentation.

Definition File

Specify your configuration/definition file using the --definition or -d flag. Supported extensions are .cjs, .json, .yml, and .yaml.

Input Files

Input files are passed as positional arguments after the definition flag. You can provide them individually or use glob patterns to match multiple files (e.g., *.js or **/*.js). Paths are relative to the current working directory.

Output File

By default, the output is saved to swagger.json. Use the -o flag to specify a custom output path. If the output file extension is .yaml or .yml, the specification will be saved in YAML format.

You can source parts of your specification from external YAML files. When these files are included in the apis array of your configuration, you can reference YAML anchors or definitions from those files within your JSDoc annotations.

/**
 * @swagger
 * /aws:
 *   get:
 *     description: contains a reference outside this file
 *     x-amazon-apigateway-integration: *default-integration
 */
app.get('/aws', (req, res) => {
  // Your implementation comes here ...
});

To begin using swagger-jsdoc, follow the quick-start guides available in the documentation:

• First steps: Follow the FIRST-STEPS.md guide for initial setup and basic usage.
• CLI usage: If you want to use the command-line interface, refer to the CLI documentation.
• Examples: Explore the examples directory to see real-world implementations and patterns.