New library for simplifying API specs in full-stack typescript projects

[ericleib]

I'm working on a library to simplify the interface between back-end and front-end in full-stack Typescript projects (eg. Nestjs API and Angular app).

A common practice to ensure consistency between back-end and front-end is to do the following:

• Use decorators in the backend code (eg. from @nestjs/swagger)

• Generate an OpenAPI spec

• From this spec, generate a client library that can be used in the front-end project (eg from ng-openapi-gen)

What if we could skip the code generation step, reduce the amount of decorators in the back-end code, without losing the benefit of type-safety and request validation?

Here is the approach I am taking:

• Specify models with zod:

const user = z.object({
  firstName: z.string(),
  lastName: z.string(),
});

• Specify API endpoints ("operations" in OpenAPI terms) using these models:

const createUser = operation({
  method: 'POST',
  body: user
});

const getUser = operation({
  method: 'GET',
  path: '/{userId}',
  routeParams: z.object({userId: z.coerce.number(),}),
  response: z.array(user),
});

const getUsers = operation({
  method: 'GET',
  queryParams: z.object({userId: z.coerce.number()}).optional(),
  response: z.array(user),
});

• Group operations into "resources":

const userResource = {
  path: '/users',
  tags: ['Users'],
  operations: {
    createUser,
    getUser,
    getUsers
  }
}

From there, you get 3-for-1:

• Type-safe HTTP client for the front-end

• Type-safe controller interfaces for the backend (in particular for Nestjs, but it could work for other frameworks)

• Generated OpenAPI spec (using zod-to-json-schema)

Here is a gist with a full example to give you an idea.