Automatic Swagger Docs generation like Elysia or NestJS

[a4arpon]

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.

[EdamAme-x]

Same👍

[yusukebe]

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.

[fzn0x]

I think Zod OpenAPI Hono is enough, just create other router file for OpenAPI instead of just Hono Router, isn't it?

[a4arpon]

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.

[yusukebe]

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.

[a4arpon]

I understand. But how they implemented it https://deno.land/x/danet@2.4.0

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

[a4arpon]

This is the repo. https://github.com/Savory/Danet-Swagger/tree/main

I think you can check it @yusukebe

[ryuapp]

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

[marcomuser]

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

[Meess]

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

[thenbe]

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.

[Meess]

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).

[imjlk]

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

[marcomuser]

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! 🎉

[miyaji255]

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