gem-hunter

Zodios Openapi

What is it ?

Install

> npm install @zodios/openapi

> yarn add @zodios/openapi

How to use it ?

Declare your API for fullstack end to end type safety

import { makeApi } from "@zodios/core";
import { z } from "zod";

export const userApi = makeApi([
  {
    method: "get",
    path: "/users",
    alias: "getUsers",
    description: "Get all users",
    parameters: [
      {
        name: "limit",
        type: "Query",
        description: "Limit the number of users",
        schema: z.number().positive(),
      },
      {
        name: "offset",
        type: "Query",
        description: "Offset the number of users",
        schema: z.number().positive().optional(),
      },
    ],
    response: z.array(userSchema),
    errors,
  },
  {
    method: "get",
    path: "/users/:id",
    alias: "getUser",
    description: "Get a user by id",
    response: userSchema,
    errors,
  },
  {
    method: "get",
    path: "/users/:id/comments",
    alias: "getComments",
    description: "Get all user comments",
    response: z.array(commentSchema),
    errors,
  },
  {
    method: "get",
    path: "/users/:id/comments/:commentId",
    alias: "getComment",
    description: "Get a user comment by id",
    response: commentSchema,
    errors,
  },
]);

export const adminApi = makeApi([
  {
    method: "post",
    path: "/users",
    alias: "createUser",
    description: "Create a user",
    parameters: [
      {
        name: "user",
        type: "Body",
        description: "The user to create",
        schema: userSchema.omit({ id: true }),
      },
    ],
    response: userSchema,
    errors,
  },
  {
    method: "put",
    path: "/users/:id",
    alias: "updateUser",
    description: "Update a user",
    parameters: [
      {
        name: "user",
        type: "Body",
        description: "The user to update",
        schema: userSchema,
      },
    ],
    response: userSchema,
    errors,
  },
  {
    method: "delete",
    path: "/users/:id",
    alias: "deleteUser",
    description: "Delete a user",
    response: z.void(),
    status: 204,
    errors,
  },
]);

Expose your OpenAPI documentation

import { serve, setup } from "swagger-ui-express";
import { makeApi } from "@zodios/core";
import { zodiosApp, zodiosRouter } from "@zodios/express";
import { bearerAuthScheme, openApiBuilder } from "@zodios/openapi";
import { userApi, adminApi } from "./api";

const app = zodiosApp();
const userRouter = zodiosRouter([...userApi, ...adminApi]);


app.use("/api/v1", userRouter);

const document = openApiBuilder({
  title: "User API",
  version: "1.0.0",
  description: "A simple user API",
})
  .addServer({ url: "/api/v1" })
  .addSecurityScheme("admin", bearerAuthScheme())
  .addPublicApi(api)
  .addProtectedApi("admin", adminApi)
  .build();

app.use(`/docs/swagger.json`, (_, res) => res.json(document));
app.use("/docs", serve);
app.use("/docs", setup(undefined, { swaggerUrl: "/docs/swagger.json" }));

app.listen(3000);