{"id":21283233,"url":"https://github.com/appandflow/s-express","last_synced_at":"2025-10-28T23:34:43.454Z","repository":{"id":57098286,"uuid":"304285085","full_name":"AppAndFlow/s-express","owner":"AppAndFlow","description":"Experimental wrapper around express.js with an inappropriate name that automatically generates openApi docs based on your app endpoints.","archived":false,"fork":false,"pushed_at":"2024-02-28T17:06:29.000Z","size":194,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-29T12:02:11.133Z","etag":null,"topics":["expressjs","nodejs","openapi-generator"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AppAndFlow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-10-15T10:06:28.000Z","updated_at":"2024-02-07T23:30:21.000Z","dependencies_parsed_at":"2023-02-08T08:00:33.859Z","dependency_job_id":"1349ba9c-6b8e-4897-9efd-635dcb1d247e","html_url":"https://github.com/AppAndFlow/s-express","commit_stats":{"total_commits":32,"total_committers":2,"mean_commits":16.0,"dds":0.125,"last_synced_commit":"01630fcd2604d92ff50e390f786eccff7402de12"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AppAndFlow%2Fs-express","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AppAndFlow%2Fs-express/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AppAndFlow%2Fs-express/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AppAndFlow%2Fs-express/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AppAndFlow","download_url":"https://codeload.github.com/AppAndFlow/s-express/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225715901,"owners_count":17512909,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["expressjs","nodejs","openapi-generator"],"created_at":"2024-11-21T11:07:32.247Z","updated_at":"2025-10-28T23:34:43.368Z","avatar_url":"https://github.com/AppAndFlow.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# s-express\n\n\u003cimg src=\"https://cdn.discordapp.com/attachments/688484592348561446/766241998868709406/unknown.png\"\n/\u003e\n\n[![npm (scoped)](https://img.shields.io/npm/v/@appandflow/s-express.svg)](https://www.npmjs.com/package/@appandflow/s-express)\n\n## Features\n\n- **Generates OpenApi documentation at runtime in .yaml, .json and .md**\n- **Handles async errors globally out of the box**\n- **Dead simple API and almost no config required**\n- **Provides a simple wrapper around Error**\n- **Fully backward compatible with exppres.js**\n- **Enforce json response aka contentType: application/json**\n\nIt's basically express.js with a bit more sugar and opinionated stuff. I just wanted\nsomething that would automatically generate openApi documentation based on my app\nendpoints. I know there's a lot of solutions out there for that,\nbut I wanted something with almost no config and a super simple API not far from express. Hence why I made this little package.\n\n### Installation\n\n```\n  npm i @appandflow/s-express\n```\n\n### API\n\n**Creating a server (minimal example)**\n\nYou might wanna do this in your index.ts\n\n`index.ts`\n\n```TS\nimport { createServer } from '@appandflow/s-express'\nconst IamAnExpressAppBasically = createServer()\n\n\n// Don't forget to require the files where you\n// used \"addRoute\"\nrequire('./controller');\n\n```\n\nThe returned value is basically an Express app.\nYou can of course pass some configs to `createServer(config)`.\n\n```TS\ninterface Config {\n  port?: string | number;   // default is 1337\n  useCors?: boolean;        // default is true\n  readyMessage?: string;\n  dotenvConfig?: dotenv.DotenvConfigOptions;\n  auth?: {\n    // You can provide a middleware\n    // that will be use on each routes\n    authMiddleware: RequestHandler;\n    // You can specify if you want the middleware\n    // to be active on each of your routes.\n    secureAllRoutes?: boolean;\n  };\n  doc?: {\n    // These infos will be use\n    // for the openApi doc.\n    version?: string;\n    title?: string;\n    description?: string;\n    servers?: DocServer[];\n    headers?: any[];\n  };\n  morgan?: {\n    format: string;\n    options?: morgan.Options\u003cany, any\u003e;\n  };\n  // list of app.use stuff that you want when the app boot\n  uses?: any[];\n\n  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. \n}\n\n// the server object you wish to expose in your openApi doc.\ninterface DocServer {\n  url: string;\n  description: string;\n}\n\n```\n\n**Adding a route to our server (minimal example)**\n\nYou can do this everywhere and the way you wish\nbut I'll suggest using a classic controller pattern.\n\n`controller.ts`\n\n```TS\nimport { addRoute } from '@appandflow/s-express'\n\n// First you got your callback à la express.js\n// but we slightly modificated signature\n\n// As you can see you still have access to req and res from express\n// if you really need them.\n// However now, note that any data passed towards your api\n// will be in `data`. Even if it's a GET, POST, PUT etc.., it doesn't matter\n// it all goes into `data`.\n// You can access the query params on `params` if needed.\naddRoute(({ data, req, res, params }) =\u003e {\n  // The returned value(s) is what will be send as a json response.\n  return {any: object, you: wish, to: 'return to you client'}\n}, config)\n\n\nconst config: AddRouteConfig = {...}\n\nexport interface AddRouteConfig {\n  method?: HttpMethod; // default is GET\n\n  path?: string;      // default is \"/\"\n\n  middlewares?: RequestHandler[]; // any middleware you wish to add to this endpoint\n\n  secure?: boolean; // if you provided an authMiddleware when you created the server, you can specify if it applies or not to this endpoint.\n\n  fields?: Field[]; // any fields you expect for this endpoint\n  // i.e: fields: [\"id!\", \"firstName\"]\n  // You can add a \"!\" at the end of the name of the field, this means\n  // that this field is mandatory. S-express will validate that the required fields\n  // are not undefined. Also it will be use to generate the openApi Docs.\n\n  summary?: string; // You can add a summary for this endpoint.\n  // It will be use for the openApi Docs.\n\n  description?: string; // You can add a description for this endpoint.\n  // It will be use for the openApi Docs.\n}\n\n```\n\n**SexpressError a basic Error wrapper.**\n\ntodo.\n\n```TS\nimport { SexpressError } from '@appandflow/s-express'\nthrow new SexpressError({\n    message: \"Dev error msg, this will be remove when env === production if you specify a prodMessage,\",\n    restCode: 422,\n    prodMessage: \"If you wish to have another error for once env === production.\",\n    data: {msg: \"any data you wish to add, this will be remove when env === production.\"}\n})\n\n```\n\n**Generating OpenApi Doc**\n\nYou have to set the env variable `DOC_MODE` to `true`.\nThe app will then start in doc mode and every declared endpoint\nthroughout the app will be hit by a request and capturing it returned value(s)\n\nDocumentation will be generated under `/docs`.\nYou can see an example \u003ca href=\"https://github.com/AppAndFlow/s-express/blob/master/openApiDocExample\"\u003eHere\u003c/a\u003e\n\nI suggest adding this your scripts in your package.json\n\ni.e: `openApiDoc: \"rm -rf docs \u0026\u0026 tsc \u0026\u0026 DOC_MODE=true node dist/index.js\"`\n\n## Todo(s)\n\n- **Write better documentation**\n- **Add support for authenticated api calls when generating OpenApi Doc**\n\n## This is an experimental package. Use at your own risk.\n\n## Thanks\n\n- Thanks to \u003ca href=\"https://github.com/alexcrist/json-to-pretty-yaml\"\u003ejson-to-pretty-yaml\u003ca/\u003e\n\n- Thanks to \u003ca href=\"https://github.com/theBenForce/openapi-markdown\"\u003eopenapi-markdown\u003ca/\u003e\n\n- And of course to any other open source libs used by my package.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappandflow%2Fs-express","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappandflow%2Fs-express","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappandflow%2Fs-express/lists"}