Solving Nested Object Swagger Documentation Issues in NestJs

Learn how to effectively document nested objects in `NestJs` using `@nestjs/swagger`. This guide provides a clear solution to common issues encountered with nested DTOs.
---
This video is based on the question https://stackoverflow.com/q/77444424/ asked by the user 'Sherif eldeeb' ( https://stackoverflow.com/u/12577650/ ) and on the answer https://stackoverflow.com/a/77444720/ provided by the user 'Sherif eldeeb' ( https://stackoverflow.com/u/12577650/ ) at 'Stack Overflow' website. Thanks to these great users and Stackexchange community for their contributions.

Visit these links for original content and any more details, such as alternate solutions, comments, revision history etc. For example, the original title of the Question was: @nest/swagger comments in nested objects doesn't work

Also, Content (except music) licensed under CC BY-SA https://meta.stackexchange.com/help/l...
The original Question post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license, and the original Answer post is licensed under the 'CC BY-SA 4.0' ( https://creativecommons.org/licenses/... ) license.

If anything seems off to you, please feel free to write me at vlogize [AT] gmail [DOT] com.
---
Solving Nested Object Swagger Documentation Issues in NestJs

In the world of API development, clear and concise documentation is crucial for both developers and users. Leveraging NestJs along with @nestjs/swagger allows us to automatically generate API documentation, streamlining this process. However, many developers encounter challenges when dealing with nested objects in their DTOs (Data Transfer Objects). In this post, we will explore a common issue related to documenting nested objects in NestJs and provide a straightforward solution.

The Problem

In a recent project involving NestJs and @nestjs/swagger, a developer discovered that while basic properties in DTOs were documented correctly, nested objects or arrays of objects resulted in empty representations in the generated Swagger documentation. Here is a simplified version of the code causing the issue:

[[See Video to Reveal this Text or Code Snippet]]

As you can see, the items property does not get documented properly in Swagger and leads to an empty representation, while the items2 property throws a circular dependency error.

The Solution

The solution to this problem lies in how TypeScript interfaces and classes are interpreted by @nestjs/swagger. The key takeaway is to switch from using TypeScript interfaces to using JavaScript classes. This modification enables @nestjs/swagger to correctly introspect and include nested objects in its documentation.

Steps to Implement the Solution

Change Interface to Class: Instead of defining Item as an interface, you'll want to define it as a class. This allows Swagger to properly recognize the structure and include it in the documentation.

Here's how you can modify the code:

[[See Video to Reveal this Text or Code Snippet]]

Adjust the CreateCheckoutDto Class: Make sure your CreateCheckoutDto still references the Item class for the items property.

Updated CreateCheckoutDto should look like this:

[[See Video to Reveal this Text or Code Snippet]]

Expected Outcome

By following these steps, you should now see that the items property is no longer empty in your Swagger documentation. It should accurately reflect the structure of the Item class, appreciating the nested object.

Conclusion

Dealing with @nestjs/swagger in a NestJs project can sometimes throw a curveball, especially when it comes to nested structures. However, by replacing TypeScript interfaces with classes, we can overcome common documentation hurdles. This simple adjustment not only resolves the issue but also enhances the clarity of your API documentation.

If you encounter similar issues or have additional questions about using NestJs with Swagger, feel free to leave a comment below!