Implement OpenAPI docs generation #9

New issue

Open

opened 2025-07-22 12:32:06 +00:00 by chartgerink · 2 comments

chartgerink commented

2025-07-22 12:32:06 +00:00

Owner

To create a professional and easy to use + build on API it is helpful to have public documentation for people.

#1 takes the first step to realizing this (among other things), and based on that we can generate these docs as static assets for high performance and findability. There's a lot of tools to do this, and the most salient is Swagger UI.

Swagger UI is recognizable by many, but personally, I don't really like it because it's everywhere. It is a great departure point nonetheless and I admit, my fallback option. However, I would be thrilled if we could get an experience that is more than merely okay.

This thread is to share resources, thinking, questions.

Resources

To create a professional and easy to use + build on API it is helpful to have public documentation for people. #1 takes the first step to realizing this (among other things), and based on that we can generate these docs as static assets for high performance and findability. There's [a lot of tools](https://openapi.tools) to do this, and the most salient is [Swagger UI](https://swagger.io/tools/swagger-ui/). [Swagger UI](https://github.com/swagger-api/swagger-ui) is recognizable by many, but personally, I don't really like it because it's everywhere. It is a great departure point nonetheless and I admit, my fallback option. However, I would be thrilled if we could get an experience that is more than merely okay. This thread is to share resources, thinking, questions. ## Resources - https://scalar.com - https://buildwithfern.com - https://www.speakeasy.com - https://www.stainless.com - https://openapi.tools/#documentation

chartgerink added the

enhancement

help wanted

question

labels

2025-07-22 12:32:15 +00:00

chartgerink commented

2025-07-22 12:36:54 +00:00

Author

Owner

https://zudoku.dev

chartgerink commented

2025-07-22 13:04:52 +00:00

Author

Owner

It looks like the initial draft implementation in #10 already includes swagger-ui 👍

This issue is still good to discuss, as it would remain preferable to not have the docs on the API route directly and generated dynamically – but on an entirely separate domain and statically generated.

It looks like the initial draft implementation in #10 already includes swagger-ui 👍 This issue is still good to discuss, as it would remain preferable to not have the docs on the API route directly and generated dynamically – but on an entirely separate domain and statically generated.