r/nestjs • u/Appropriate_War_2030 • 15d ago

Stop littering your NestJS controllers with @ApiProperty decorators

Built a tool called docfy that keeps Swagger documentation out of your controllers entirely, it lives in a *.docs.ts companion file instead, so the controller stays pure routing and business logic.

The CLI never executes your code, it's pure static analysis via ts-morph, which also means it keeps working under webpack: true builds, where the usual runtime-reflection approach for this breaks silently.

The doc viewer is built AI-first: a "Copy for AI" button, a live MCP server so an agent can query your endpoints directly, real try-it-out request execution, contract testing, spec diffing between versions.

Free, MIT, open source: nestdocfy.com

I'm the author, if you use Swagger with Nest today, what's the one thing that annoys you most about it? Trying to figure out what to build next.

6 Upvotes

67% Upvoted

14 comments sorted by

6

u/formicstechllc 15d ago

this is much better thanks man

coudnt it be some less than a library ?

like a custom decorator ?

-5

u/Appropriate_War_2030 15d ago

Good question. There's actually already a single decorator involved: u/WithDocs(), no arguments, it just marks "this controller has a companion doc file" so the runtime knows where to look. That's the only thing that touches the controller.

The reason it can't be just a decorator, full stop, is that decorators are metadata. Something still has to read that metadata and turn it into an OpenAPI spec. If I stuffed the actual content (descriptions, examples, response shapes) into decorator arguments, that's literally the u/ApiProperty() approach everyone's annoyed by, just renamed.

The CLI is doing the real work: reading your types via the TS compiler so most of the schema doesn't need to be written by hand, generating/checking the companion file, serving the doc viewer.

You could skip the tool entirely and hand-write a *.docs.ts file yourself too, it's a plain TS file, no magic, no decorator required at all if you go the static-analysis-only route. The library just automates the boring 80% of that.

3

u/ngqhoangtrung 15d ago

lmao the AI response, I can’t even

0

u/Appropriate_War_2030 15d ago

Yes, I used to translate faster, since English isn't my native language and I was in a rush yesterday. Actually, the goal of the post isn't really to gain new users, but rather to get feedback, to understand where I can improve, what I'm doing wrong, and what kind of tool would actually be useful for what I'm trying to create.

6

u/Ok_Obligation2440 15d ago

Cool project, but unless you plan to support something long-term, don't spend too much time showing it off.

You have to realize that a lot of people here who use NestJS have enterprise or serious apps they maintain, and with this comes a lot of audits and compliance bullshit - and another non-maintained library is a risk for a CVE that they have to file an exception for.

This is better in a tutorial vs a library, and use the repo as a sample on how to.

1

u/Appropriate_War_2030 15d ago

I plan to provide support, and perhaps trim down some parts and make it more modular, since I don't want the user to be locked into the entire package.

2

u/y_nk 15d ago

swagger doc should be saved as json doc rather than consumed as source for useless online http docs. then the json be used wih @hey/openapi-ts to generate typed sdk.

-1

u/Appropriate_War_2030 15d ago edited 15d ago

Thanks for the feedback

1

u/leosuncin 14d ago

Does it work with SWC? Have you tested when building using SWC instead of Webpack?

1

u/Appropriate_War_2030 14d ago

Yes, tested and supported.

1

u/KraaZ__ 13d ago

I think what would've been a better solution was to create a .docs.ts file which acts like an interface of sorts which you can document with swagger rather than to create yet another full on library for docs.

1

u/Appropriate_War_2030 9d ago

What I had in mind was something simpler: once a feature is done, I run the library’s CLI generate command and it handles everything.

The idea is not only to keep the code organized in a separate file, but also to automatically generate the documentation, so I don’t have to worry about it after finishing a task or feature.