Deno, Hono, Zod Open API, Swagger UI

README.md

Deno, Hono, Zod Open API, Swagger UI

See :

• https://hono.dev/middleware/third-party
• https://github.com/honojs/middleware/tree/main/packages/zod-openapi
• https://github.com/honojs/middleware/tree/main/packages/swagger-ui

Script

Run deno run -A --allow-env --unstable --watch server.ts

Result

API

• Success : http://localhost:8000/users/122
• Error : http://localhost:8000/users/1

Scheme for OPEN API

• http://localhost:8000/doc

Swagger UI (use scheme at /doc)

• http://localhost:8000/ui

Scalar UI (use scheme at /doc)

• http://localhost:8000/reference

deps.ts

export { Hono } from "https://deno.land/x/hono@v3.12.6/mod.ts";
export { createRoute, OpenAPIHono, z } from "npm:@hono/zod-openapi";
export { swaggerUI } from "npm:@hono/swagger-ui";

export { apiReference } from 'npm:@scalar/hono-api-reference'

server.ts

import { z, createRoute, OpenAPIHono, swaggerUI, apiReference } from './deps.ts'

const ParamsSchema = z.object({
  id: z
    .string()
    .min(3)
    .openapi({
      param: {
        name: 'id',
        in: 'path',
      },
      example: '1212121',
    }),
})

const UserSchema = z
  .object({
    id: z.string().openapi({
      example: '123',
    }),
    name: z.string().openapi({
      example: 'John Doe',
    }),
    age: z.number().openapi({
      example: 42,
    }),
  })
  .openapi('User')


  const ErrorSchema = z.object({
    code: z.number().openapi({
      example: 400,
    }),
    message: z.string().openapi({
      example: 'Bad Request',
    }),
  })


const route = createRoute({
  method: 'get',
  path: '/users/{id}',
  request: {
    params: ParamsSchema,
  },
  responses: {
    200: {
      content: {
        'application/json': {
          schema: UserSchema,
        },
      },
      description: 'Retrieve the user',
    },
    400: {
        content: {
          'application/json': {
            schema: ErrorSchema,
          },
        },
        description: 'Returns an error',
      },
  },
})

const app = new OpenAPIHono()

app.openapi(route, (c) => {
  const { id } = c.req.valid('param')
  return c.json({
    id,
    age: 20,
    name: 'Ultra-man',
  })
})

// The OpenAPI documentation will be available at /doc
app.doc('/doc', {
  openapi: '3.1.0', // 3.0.0
  info: {
    version: '1.0.0',
    title: 'My API',
  },
})

// Use Scalar
app.get(
  '/reference',
  apiReference({
    spec: {
      url: '/doc',
    },
  }),
)

// OR Use the middleware to serve Swagger UI at /ui
app.get('/ui', swaggerUI({ url: '/doc' }))

Deno.serve(app.fetch)