@sleekify/sleekify v1.2.4

Sleekify

This project's goal is to simplify the development of REST web services in NodeJS by bringing the best of the Java API for RESTful Web Services (JAX-RS) to TypeScript. This is possible since TypeScript decorators may be used in a manner similar to Java annotations. This project allows you to apply decorators to your resource classes to identify your REST resources and associate them with OpenAPI definitions. This allows you to maintain your API documentation alongside your code using typed definitions. If you ever had to maintain a large OpenAPI specification by hand, this should grab your attention. Your API documentation will both match the OpenAPI specification's schema and be generated from your code.

Versions

Getting Started

Follow the instructions provided by each integration:

• Fastify: https://github.com/sleekify/sleekify-fastify

API Reference

Introduction

src/v1/users.ts

@Path('/v1/users')
@Schema({
  $ref: '#/components/schemas/user'
})
export class UsersIdResource {
  @GET()
  async getMany () {
    // TODO: your read user code here
  }

  @POST()
  async createOne () {
    // TODO: your create user code here
  }
}

This simplified example shows how the decorators are intended to be used. Each class represents a REST resource which is identified by a path. The resource class's methods provide the operations or actions you may execute on the resource. It's not required, but it is generally a good practice to have the class file path match the resource's relative path.

Decorator Inheritance

The example above was simple, but when you start fully documenting your API, the OpenAPI definitions can become overwhelming. Decorator inheritance allows you to split the OpenAPI definitions across a resource class hierarchy.

src/v1/AbstractSingleResource.ts

@Components({
  parameters: {
    id: {
      description: 'The identifier of the resource',
      name: 'id',
      in: 'path',
      required: true,
      schema: {
        $ref: '#/components/schemas/id'
      }
    }
  },
  schemas: {
    id: {
      description: 'The id path parameter schema',
      type: ['integer']
    }
  }
})
export abstract class AbstractSingleResource {
  @GET({
    responses: {
      400: {
        $ref: '#/components/responses/400'
      },
      401: {
        $ref: '#/components/responses/401'
      },
      403: {
        $ref: '#/components/responses/403'
      },
      404: {
        $ref: '#/components/responses/404'
      },
      500: {
        $ref: '#/components/responses/500'
      }
    }
  })
  async getOne () {
    // TODO: your generic read code here
  }
}

Your base classes can provide all of the common documentation, while your subclasses may be more specialized for each individual resource. This pattern works because REST APIs usually follow a consistent interface. The values you provide for the decorators are additive allowing you to add or replace properties in the OpenAPI definitions. If you ever need to remove a property from an OpenAPI definition, you must define a new base class without that property.

src/v1/users.ts

@Components({
  schemas: {
    user: {
      type: ['object'],
      properties: {
        id: {
          type: ['number']
        },
        name: {
          type: ['string']
        }
      }
    }
  }
})
@Path({
  path: '/v1/users/{id}',
  parameters: [
    {
      $ref: '#/components/parameters/id'
    }
  ]
})
@Schema({
  $ref: '#/components/schemas/user'
})
export class UsersIdResource extends AbstractSingleResource {
  @GET({
    description: 'Retrieve a single user by ID'
  })
  async getOne () {
    return await super.getOne();
  }
}

In the example above, UserIdResource will inherit the @GET responses from AbstractSingleResource and add its own description for the GET operation.

Class Decorators

Method Decorators

OpenAPI Types

This project also provides you with types for all of the OpenAPI schema objects. All of the types follow a consistent naming pattern which matches the schema names in OpenAPI Specification v3.1.1. For example, if you need the type for the Operation Object schema, then you would import OperationObject.

import { type OperationObject } from '@sleekify/sleekify';

The Annotation Utility

This utility allows you to search for classes which have an Sleekify decorator or inspect individual classes and class methods for decorators.

Web Application Errors

These web application errors are provided since throwing errors is the best approach for generating error responses. This prevents HTTP concerns from leaking into other application layers and allows you to take advantage of error chaining via the error cause property. You may define your own error handler to serialize errors into error responses which keeps error formatting in a single code location.

Client Errors

Server Errors