(Typescript) Express API with input Validation and Swagger UI
Thats a mouthful isn't it.
- Typescript: The language used, a superset of Javascript with optional static types
- Express: Minimalist framework to create APIs
- Validation: The expected input is defined by a schema. If the input does not follow this schema it is rejected (instead of crashing the server)
- Swagger UI: An automatically generated documentation and testing tool to interface with the api
Usage
This section will shortly describe your expected development process.
- Create a schema that you want to receive in
src/types/schemas.ts - Create a new controller in
src/controllers - Add the following line to your controller to specify the schema you want to receive at an endpoint (for an, example see
src/controllers/user.ts):// #swagger.parameters['body'] = {in: "body", schema: { $ref: "#/schemas/UserPostRequest" }}=> This will validate the input to be the same schema as UserPostRequest insrc/types/schemas.ts
- Add your controller to
src/routes.ts
Then to run your project execute the following commands:
$ npm install # Install dependencies$ npm run schema # Turn your schemas into JSON to be used for input validation (result is put in build/_schema.ts)$ npm run spec # Generate the Swagger UI definition (result is put in build/swagger.json)- Alternatively run
$ npm run swaggerto execute both previous commands
- Alternatively run
$ npm run dev # Start the server
The Swagger UI is accessible on http://localhost:3000/docs.
Project structure explanation
This section will shortly explain the purpose of each file and folder.
build: Place to store generated files, I recommend you don't touch thisbuild/_schema.ts: JSON representation of the schemas specified insrc/types/schemas.tsbuild/swagger.json: JSON representation of the swagger UI generated from your project code
utils: Holds the scripts that generate schema and swagger UI filesutils/schemaGenerator.js: Used to generatebuild/_schema.tsfromsrc/types/schemas.tsutils/swagger.ts: Used to generatebuild/swagger.jsonfrom your entiresrcdirectory
src: Holds all your source filessrc/index.ts: Entrypoint of your entire applicationsrc/routes.ts: Specifies endpoints and attaches controllers to requests to that endpointsrc/controllers/: Each endpoint has a controller that handles the requests. Each controller has a seperate file.src/middleware/: Here you can put additional middleware for things like authenticationsrc/types/: Holdes your type definitions / schemas. These are used for input validation when a request is made. If a request does not present data that matches the schema then the request is rejected.
33 Dec 27, 2022
3 May 18, 2022
4 May 3, 2022
14 Jan 3, 2023
14 Jul 2, 2022
6 May 29, 2022
3 Oct 1, 2022
220 Nov 7, 2022
13 Dec 29, 2022
6 Jul 12, 2022