honojs
Automatic Swagger Docs generation like Elysia or NestJS
What is the feature you are proposing?
First I'm giving thank's to Hono team for creating this amazing framework. But now a days every modern framework has automatic doc generation feature. I love hono. It's great. But writing Doc separately is too time consuming for me. You can say we have hono/swagger with zod support but writing api like this is not also appropriate for me or my team. Framework now a days typebox or something this kind of package under the hood to create api automatically.
I am requesting Hono team if they can do this it will be very great. I have tried to do this but not successful. Api docs is very important for my team and We don't have enough times to create another doc or add zod to write apis.
Please if you can implement this feature it will be very great.
Hi @a4arpon
Is not Zod OpenAPI Hono enough? To generate the Sagger docs, we will need a third-party library since we don't have a built-in validator. It will be third-party middleware or a wrapper class. One of the ideas is Zod OpenAPI Hono. It's good.
I think Zod OpenAPI Hono is enough, just create other router file for OpenAPI instead of just Hono Router, isn't it?
What is the point to create a route zod value first then create the original route. But docs writing is nowadays a time consuming task. Sonner or later we need this automatic doc generation. We all appreciate your hard working and dedication for the framework. But we are asking you a little bit more. Can you please do this? 🫠. If it can be done then a lot's of time will be saved on development. Cause our company is using hono but doc writing is too too complicated for us. And many of us i mean hono users requesting this feature.
Can you please do this?
As mentioned above, I can only say, please use Zod OpenAPI Hono. It is getting many users, such as Unkey is heavily using it. We don't have any plan for generating the Swagger document feature in the ~~Hono "core"~~ hono package. Instead, Zod OpenAPI Hono is hosted outside of the hono package, i.e. in honojs/middleware, and someone may create a different Swagger document-generating Hono wrapper or middleware.
There is a historical background to this, and like you, there have been many requests for OpenAPI documentation features for a long time. I had always struggled with how to implement it, but we solved the problem by creating Zod OpenAPI Hono. So that is the answer.
I understand. But how they implemented it https://deno.land/x/[email protected]
I think danet has a feature to generate docs automatically. You can see it. I think you will get some ideas. I am looking at into it too
This is the repo. https://github.com/Savory/Danet-Swagger/tree/main
I think you can check it @yusukebe
Hello @a4arpon. I don't know what you are asking for. Does it mean that you would like to use Swagger library without validation library like Zod?
import { Hono } from 'hono'
import { swagger } from '@hono/swagger' // imaginary
const app = new Hono()
app.use(swagger())
app.get('/', (c) => {
return c.text('Hello Hono!')
})
export default app
The way fastify is solving this specific issue is fantastic. It uses json schema for request/response validation which then also allows for pretty much automatic openapi documentation. The schema for each route can be authored directly in json schema or via a type adapter in typebox/zod/etc.
For inspiration see the fastify openapi documentation https://github.com/fastify/fastify-swagger
typia uses a typescript transformer with which it's possible to reflect the types to runtime variables, i.e. they can runtime typecheck against a type (magic 🪄 ). Which could be looked into as a solution, see my answer in a duplicate issue: https://github.com/honojs/hono/issues/3069#issuecomment-2204523964
I opened a duplicate issue (https://github.com/honojs/hono/issues/3069) as I wasn't aware of this one, but that thread has some relevant discussion. Specifically, an approach used by nestia to automatically generate the openapi schema. That approach is particularly interesting because it generates the schema from typescript types and does not require a user to explicitly write the openapi route properties, which are very verbose (e.g. see the diff required for a simple endpoint).
And because hono already does a fantastic job of inferring the types for each route, then a similar approach to nestia could mean that hono would be able to generate openapi schemas for any hono app written using typescript, including existing hono apps that do not use @hono/zod-openapi.
I opened a duplicate issue (#3069) as I wasn't aware of this one, but that thread has some relevant discussion. Specifically, an approach used by nestia to automatically generate the openapi schema. That approach is particularly interesting because it generates the schema from typescript types and does not require a user to explicitly write the openapi route properties, which are very verbose (e.g. see the diff required for a simple endpoint).
And because hono already does a fantastic job of inferring the types for each route, then a similar approach to nestia could mean that hono would be able to generate openapi schemas for any hono app written using typescript, including existing hono apps that do not use
@hono/zod-openapi.
Nothing is free but Nestia for swagger generation seem to use typia, which heavily relies on type hints added to each route (which typia can use). It's definitely not as simple as "nestia does it so we can also easily do it", it's going to be quite complex (and with that also quite some effect to maintain while Hono is evolving), and still when this can be automatically generated you want to be able to easily extend is (e.g. typescript doesn't have a type that specifies that a string can have max 16 characters or something).
That said it's a very interesting angle, and would very interesting if we could could automatically generate a standard openApi spec that might be generic but correct. And similar to Nestia add extra typia tags to enhance the schema if we want a more detailed openApi definitition (e.g. max 16 chars string).
If following nestia's approach, hono already has typia validator, and recently typia 3rd party library is released - unplugin-typia, so someone could be able to create this feature. but it will require more effort from the typia community than hono.
See also this
By the way, setting up typia is very easy with this hono example
Just some more thoughts on this. OpenAPI is basically just a JSON Schema. Hono has a really nice and simple validator built-in which could be used with JSON Schema definitions as well. I've just discovered that there indeed is already a Typebox validator middleware package for Hono. Now for those that don't know, Typebox is similar to Zod but it spits out JSON Schemas instead of Zod's propriertary/custom format. This means that with this Typebox middleware we are already at a point where we are using JSON Schemas to describe the request validators. The missing link now would be a package on top which would allow - similarly to zod-openapi - to describe all request handlers with the required OpenAPI properties and use Typebox for the schemas. This way we could get validation AND the OpenAPI documentation for SwaggerUI in one go. AFAIK, this is pretty much exactly how Fastify handles it. Benefits would be:
- Reliance on web/industry standards (JSON Schema) with all its promises of stability
- No conversions between different formats. It's JSON Schema all the way
- According to the benchmarks, Typebox is seriously fast. We could look into if this would make a significant difference overall in comparison to the zod-openapi setup
As a starting point we could look into "forking" zod-openapi and modify it to create typebox-openapi. In theory, it should be simpler as it's already JSON Schema and doesn't need any extra package to convert from Zod (famous last words... We'll see 😆). Once we have that we could think about whether it makes sense to move the common layer between the packages closer into Hono itself? Maybe there is a neat way of doing that so that no special Hono classes need to be imported in order to create a OpenAPI annotated REST API with Hono. That would be neat! 🎉
I am creating an OpenAPI Schema Generator for typia. This is implemented with typia's JSON Schema generator.
https://github.com/miyaji255/hono-typia-openapi
Hey 👋🏼, I'm working on something similar, hono-openapi! It's still new, so the API might change, but I believe it’s pretty straightforward to implement. I'd love to hear your thoughts, and any feedback on improvements would be super helpful. Thanks!
https://github.com/rhinobase/hono-openapi
This looks very promising! 😍 Even better than what I had in mind. Great initiative!
Following up on this, is there a good alternative library so far if I want auto swagger generation with no need to do extra types and schemas etc ... like FastApi or Spring Boot ?
How is this supposed to work without schemas or types? Don't you also have to annotate your classes with decorators in spring boot?
To me the currently best way is to use hono-openapi. That library solved this bug ticket for me.
In every other language/framework you just work on your app and the docs are auto-generated ...
idk how it's done exactly under the hood (maybe it references the types you already use normally) but in hono its the uncommon way to do all this boilerplate and complicated types everywhere
Just try and bootstrap a C# .net app or a python fastapi and you will get swagger by default with 0 config or 0 boilerplate to write , you just write your functions and that's it (it also work for java spring you just have to add a dependency)
Here are the packages that auto generate based on your routes :
https://www.nuget.org/packages/swashbuckle.aspnetcore.swaggergen/ https://springdoc.org/ https://fastapi.tiangolo.com/reference/openapi/docs/
Hi! 👋 Thanks for raising this — totally agree that automatic OpenAPI generation is essential in modern TypeScript-first frameworks.
If you're using Hono, you might want to check out [@rcmade/hono-docs](https://www.npmjs.com/package/@rcmade/hono-docs) — it's a CLI tool that auto-generates OpenAPI 3.0 spec and TypeScript snapshots directly from your Hono route types using ts-morph. No need to write Zod schemas just for docs — it works by analyzing your existing Hono AppType.
✨ Features:
- Minimal config
- Pure TypeScript type-based docs
- CLI + programmatic API
pnpm add -D @rcmade/hono-docs
hono-docs generate --config hono-docs.ts
AI message, a package created yesterday (probably with AI as well)… I'll wait for an Hono implementation, thanks.
