Feature/philip/auto doc generation

[PhilipWee]

WHAT

An incredibly crude proof of concept for automatically generating the responses and paths automatically rather than having users manually update it

#809

WHY

To keep code DRY

HOW

The following is a general idea of how the proof of concept works, I'll fix the edge cases if the general direction is okay

1. From the api paths, glob the relevant App router files
2. Craft a Record<string,string> with the api route as key and code in the file as the contents
3. Find all comments in the code (I used babel which should handle most edge cases)
4. For each comment, parse it with doctrine (I copied the idea from swagger-jsdoc)
5. For each parsed doctrine, parse it into yaml (Also copied from swagger-jsdoc)
6. Validate the schema with zod (I'm assuming you're familiar with zod from your work from the next-validations library)
7. From the parsed schema add it into the OAS3 specification
8. Continue swagger doc generation as per normal

LIMITATIONS

I'll only make it work for App router for now, if people request for Pages router, I'll do that but my spider senses tell me there's alot of edge cases for that.

Also I'm only going to make it work for routes defined in a very specific format first, (The export const GET = blabla format) because I'm too lazy to handle edge cases - We can do it the prettier way and blame everything on the end user and say that its our way or the highway

STEPS

I have done none of these lmao, will do after proof of concept gets go ahead

• Linter
• Tests
• Review comments
• Security

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7efdf37

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
next-swagger-doc	❌ Failed (Inspect)			Oct 1, 2023 0:16am
next-swagger-doc-demo	❌ Failed (Inspect)			Oct 1, 2023 0:16am

[ghost]

👇 Click on the image for a new way to code review

Legend

[socket-security]

New dependencies detected. Learn more about Socket for GitHub ↗︎

Packages	Version	New capabilities	Transitives	Size	Publisher
glob	10.3.10	None	+0	454 kB	isaacs
@babel/parser	7.23.0	None	+0	1.89 MB	nicolo-ribaudo

[jellydn]

Hi @PhilipWee Is this ready to review?

I'll only make it work for App router for now, if people request for Pages router, I'll do that but my spider senses tell me there's alot of edge cases for that.

Regards this point, I don't think a lot of people really using nextjs 13 on production. It would be good if we could support page route along with app route. What do you think?

[PhilipWee]

@jellydn Okay I'll think about how to make the pages router work, shouldn't be too hard

Its not ready for review, I just wanted your thoughts on the implementation

Specifically the following:

The following is a general idea of how the proof of concept works, I'll fix the edge cases if the general direction is okay

From the api paths, glob the relevant App router files
Craft a Record<string,string> with the api route as key and code in the file as the contents
Find all comments in the code (I used babel which should handle most edge cases)
For each comment, parse it with doctrine (I copied the idea from swagger-jsdoc)
For each parsed doctrine, parse it into yaml (Also copied from swagger-jsdoc)
Validate the schema with zod (I'm assuming you're familiar with zod from your work from the next-validations library)
From the parsed schema add it into the OAS3 specification
Continue swagger doc generation as per normal

[jellydn]

Hi @PhilipWee Your approach should work. Just a few comments on how we should build the library.

Validate the schema with zod

Zod doesn't support tree-shaking well. Have you ever tried valibot? Good reference if you want to take a look https://www.builder.io/blog/valibot-bundle-size

From the parsed schema add it into the OAS3 specification

It would be good if we have an option for user choose the what is the output they want.

[Supported specifications](https://github.com/Surnet/swagger-jsdoc#supported-specifications)
OpenAPI 3.x
Swagger 2
AsyncAPI 2.0