Skip to content

Experimental wrapper around express.js with an inappropriate name that automatically generates openApi docs based on your app endpoints.

Notifications You must be signed in to change notification settings

AppAndFlow/s-express

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

32 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

s-express

npm (scoped)

Features

  • Generates OpenApi documentation at runtime in .yaml, .json and .md
  • Handles async errors globally out of the box
  • Dead simple API and almost no config required
  • Provides a simple wrapper around Error
  • Fully backward compatible with exppres.js
  • Enforce json response aka contentType: application/json

It's basically express.js with a bit more sugar and opinionated stuff. I just wanted something that would automatically generate openApi documentation based on my app endpoints. I know there's a lot of solutions out there for that, but I wanted something with almost no config and a super simple API not far from express. Hence why I made this little package.

Installation

  npm i @appandflow/s-express

API

Creating a server (minimal example)

You might wanna do this in your index.ts

index.ts

import { createServer } from '@appandflow/s-express'
const IamAnExpressAppBasically = createServer()


// Don't forget to require the files where you
// used "addRoute"
require('./controller');

The returned value is basically an Express app. You can of course pass some configs to createServer(config).

interface Config {
  port?: string | number;   // default is 1337
  useCors?: boolean;        // default is true
  readyMessage?: string;
  dotenvConfig?: dotenv.DotenvConfigOptions;
  auth?: {
    // You can provide a middleware
    // that will be use on each routes
    authMiddleware: RequestHandler;
    // You can specify if you want the middleware
    // to be active on each of your routes.
    secureAllRoutes?: boolean;
  };
  doc?: {
    // These infos will be use
    // for the openApi doc.
    version?: string;
    title?: string;
    description?: string;
    servers?: DocServer[];
    headers?: any[];
  };
  morgan?: {
    format: string;
    options?: morgan.Options<any, any>;
  };
  // list of app.use stuff that you want when the app boot
  uses?: any[];

  controllersPath?: string; // this is the URI to access your controllers folder i.e: "src/controllers". If you don't provide this, you'll need to require those files/folder by yourself. 
}

// the server object you wish to expose in your openApi doc.
interface DocServer {
  url: string;
  description: string;
}

Adding a route to our server (minimal example)

You can do this everywhere and the way you wish but I'll suggest using a classic controller pattern.

controller.ts

import { addRoute } from '@appandflow/s-express'

// First you got your callback à la express.js
// but we slightly modificated signature

// As you can see you still have access to req and res from express
// if you really need them.
// However now, note that any data passed towards your api
// will be in `data`. Even if it's a GET, POST, PUT etc.., it doesn't matter
// it all goes into `data`.
// You can access the query params on `params` if needed.
addRoute(({ data, req, res, params }) => {
  // The returned value(s) is what will be send as a json response.
  return {any: object, you: wish, to: 'return to you client'}
}, config)


const config: AddRouteConfig = {...}

export interface AddRouteConfig {
  method?: HttpMethod; // default is GET

  path?: string;      // default is "/"

  middlewares?: RequestHandler[]; // any middleware you wish to add to this endpoint

  secure?: boolean; // if you provided an authMiddleware when you created the server, you can specify if it applies or not to this endpoint.

  fields?: Field[]; // any fields you expect for this endpoint
  // i.e: fields: ["id!", "firstName"]
  // You can add a "!" at the end of the name of the field, this means
  // that this field is mandatory. S-express will validate that the required fields
  // are not undefined. Also it will be use to generate the openApi Docs.

  summary?: string; // You can add a summary for this endpoint.
  // It will be use for the openApi Docs.

  description?: string; // You can add a description for this endpoint.
  // It will be use for the openApi Docs.
}

SexpressError a basic Error wrapper.

todo.

import { SexpressError } from '@appandflow/s-express'
throw new SexpressError({
    message: "Dev error msg, this will be remove when env === production if you specify a prodMessage,",
    restCode: 422,
    prodMessage: "If you wish to have another error for once env === production.",
    data: {msg: "any data you wish to add, this will be remove when env === production."}
})

Generating OpenApi Doc

You have to set the env variable DOC_MODE to true. The app will then start in doc mode and every declared endpoint throughout the app will be hit by a request and capturing it returned value(s)

Documentation will be generated under /docs. You can see an example Here

I suggest adding this your scripts in your package.json

i.e: openApiDoc: "rm -rf docs && tsc && DOC_MODE=true node dist/index.js"

Todo(s)

  • Write better documentation
  • Add support for authenticated api calls when generating OpenApi Doc

This is an experimental package. Use at your own risk.

Thanks

About

Experimental wrapper around express.js with an inappropriate name that automatically generates openApi docs based on your app endpoints.

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published