https://github.com/lzehrung/zod-express-openapi-routes

POC for cozy API validation, typing, and OpenAPI/swagger schema generation with Zod and Express
https://github.com/lzehrung/zod-express-openapi-routes

api api-routes documentation-as-code express nodejs openapi openapi3 swagger typescript validation zod

Last synced: 3 months ago
JSON representation

POC for cozy API validation, typing, and OpenAPI/swagger schema generation with Zod and Express

• Host: GitHub
• URL: https://github.com/lzehrung/zod-express-openapi-routes
• Owner: lzehrung
• Created: 2022-12-12T06:37:15.000Z (about 2 years ago)
• Default Branch: main
• Last Pushed: 2024-04-21T22:36:47.000Z (9 months ago)
• Last Synced: 2024-08-01T08:11:37.177Z (6 months ago)
• Topics: api, api-routes, documentation-as-code, express, nodejs, openapi, openapi3, swagger, typescript, validation, zod
• Language: TypeScript
• Homepage:
• Size: 19.1 MB
• Stars: 6
• Watchers: 1
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

• awesome - lzehrung/zod-express-openapi-routes - POC for cozy API validation, typing, and OpenAPI/swagger schema generation with Zod and Express (TypeScript)

README

        
## Overview

- Find an ergonomic way (minimize boilerplate and code duplication) to get typed, zod-validated express routes and an OpenAPI

  schema at the same time

- Minimize code duplication and boilerplate between express routes, request parameter validation, and OpenAPI definitions

## Highlights

- base `Controller` class that consolidates creation of express route, zod-validated request parameters, OpenAPI definition, and getting a typed `express.RouteHandler`: [src/zod-openapi-express-routes/zod-api.controller.ts](src/zod-openapi-express-routes/zod-api.controller.ts)

- example controller instance: [src/products/products.controller.ts](src/products/products.controller.ts)

- example request parameter zod schemas: [src/products/api-schemas.ts](src/products/api-schemas.ts)

- example manually-defined file upload route using [multer](https://github.com/expressjs/multer) for uploads: [src/products/products.controller.ts#L148](src/products/products.controller.ts#L148)

## Run the example

- clone the repository

- `npm install`

- `npm run dev`

- open the generated OpenAPI docs http://localhost:3250/api/reference

- open the generated `swagger.json` http://localhost:3250/api/swagger.json

- get a single resource http://localhost:3250/api/products/1

- an invalid path parameter results in validation errors http://localhost:3250/api/products/abc

## Dependencies

- `@anatine/zod-openapi`: generates request parameter OpenAPI definitions from zod schemas

- `openapi3-ts`: used to define OpenAPI schema in TypeScript

- `swagger-ui-express`: serves the OpenAPI documentation

- `zod`: used to define request parameter validation schemas

## Limitations

- file upload routes must be documented manually

- haven't tested nested routers / routes

- not extensively tested