https://github.com/appandflow/s-express
Experimental wrapper around express.js with an inappropriate name that automatically generates openApi docs based on your app endpoints.
https://github.com/appandflow/s-express
expressjs nodejs openapi-generator
Last synced: 7 months ago
JSON representation
Experimental wrapper around express.js with an inappropriate name that automatically generates openApi docs based on your app endpoints.
- Host: GitHub
- URL: https://github.com/appandflow/s-express
- Owner: AppAndFlow
- Created: 2020-10-15T10:06:28.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-02-28T17:06:29.000Z (over 2 years ago)
- Last Synced: 2024-04-29T12:02:11.133Z (about 2 years ago)
- Topics: expressjs, nodejs, openapi-generator
- Language: TypeScript
- Homepage:
- Size: 189 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# s-express
[](https://www.npmjs.com/package/@appandflow/s-express)
## 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`
```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)`.
```TS
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;
};
// 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`
```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.
```TS
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
- Thanks to json-to-pretty-yaml
- Thanks to openapi-markdown
- And of course to any other open source libs used by my package.