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/[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

[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: #3069 (comment)

[thenbe]

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.

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