Skip to content

Commit c4c09b5

Browse files
tazo90tazo90
authored
feat: support for multiple schema types simultaneously (#46)
* feat: add support for multiple schema types and custom OpenAPI files - Add support for schemaType as string or array (e.g., ["zod", "typescript"]) - Add schemaFiles config option for custom YAML/JSON OpenAPI schemas - Implement priority-based schema resolution (custom files > zod > typescript) - Add js-yaml dependency for YAML parsing - Update SchemaProcessor to handle multiple schema sources simultaneously - Maintain backward compatibility with existing single schemaType config - Update types and OpenAPI template with new configuration options * docs: add next15-app-mixed-schemas example demonstrating multiple schema types - Add complete working example using Zod, TypeScript, and custom YAML schemas - Include API routes for users, products, orders, and roles - Demonstrate schema priority with custom openapi-models.yaml - Add comprehensive README with setup instructions - Update main README with Multiple Schema Types section * docs: simplify README.md * docs: fix typo in readme.md * chore: update package.json for next15-app-mixed-schemas
1 parent a887ca8 commit c4c09b5

26 files changed

+10008
-71
lines changed

‎README.md‎

Lines changed: 74 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,13 @@ Automatically generate OpenAPI 3.0 documentation from Next.js projects, with sup
44

55
## Features
66

7-
- ✅ Automatic OpenAPI documentation generation from Next.js code
8-
- ✅ Support for Next.js App Router (including `/api/users/[id]/route.ts` routes)
9-
- ✅ TypeScript types support
10-
- ✅ Zod schemas support
11-
- ✅ Drizzle-Zod support - Generate schemas from Drizzle ORM tables 🆕
12-
- ✅ JSDoc comments support
13-
- ✅ Multiple UI interfaces: `Scalar`, `Swagger`, `Redoc`, `Stoplight` and `Rapidoc` available at `/api-docs` url
14-
- ✅ Path parameters detection (`/users/{id}`)
15-
- ✅ Intelligent parameter examples
16-
- ✅ Intuitive CLI for initialization and documentation generation
7+
- ✅ Automatic OpenAPI 3.0 documentation generation from Next.js App Router
8+
- ✅ Multiple schema types: `TypeScript`, `Zod`, `Drizzle-Zod`, or `custom YAML/JSON` files 🆕
9+
- ✅ Mix schema sources simultaneously - perfect for gradual migrations 🆕
10+
- ✅ JSDoc comments with intelligent parameter examples
11+
- ✅ Multiple UI interfaces: `Scalar`, `Swagger`, `Redoc`, `Stoplight`, and `RapiDoc` available at `/api-docs` url
12+
- ✅ Auto-detection of path parameters (e.g., `/users/[id]/route.ts`)
13+
- ✅ Intuitive CLI for quick setup and generation
1714

1815
## Supported interfaces
1916

@@ -59,7 +56,8 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
5956
],
6057
"apiDir": "src/app/api",
6158
"schemaDir": "src/types", // or "src/schemas" for Zod schemas
62-
"schemaType": "zod", // or "typescript" for TypeScript types
59+
"schemaType": "zod", // or "typescript", or ["zod", "typescript"] for multiple
60+
"schemaFiles": [], // Optional: ["./schemas/models.yaml", "./schemas/api.json"]
6361
"outputFile": "openapi.json",
6462
"outputDir": "./public",
6563
"docsUrl": "/api-docs",
@@ -71,20 +69,21 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
7169

7270
### Configuration Options
7371

74-
| Option | Description |
75-
| ---------------------- | -------------------------------------------------------------------------- |
76-
| `apiDir` | Path to the API directory |
77-
| `schemaDir` | Path to the types/schemas directory |
78-
| `schemaType` | Schema type: `"zod"` or `"typescript"` |
79-
| `outputFile` | Name of the OpenAPI output file |
80-
| `outputDir` | Directory where OpenAPI file will be generated (default: `"./public"`) |
81-
| `docsUrl` | API documentation URL (for Swagger UI) |
82-
| `includeOpenApiRoutes` | Whether to include only routes with @openapi tag |
83-
| `ignoreRoutes` | Array of route patterns to exclude from documentation (supports wildcards) |
84-
| `defaultResponseSet` | Default error response set for all endpoints |
85-
| `responseSets` | Named sets of error response codes |
86-
| `errorConfig` | Error schema configuration |
87-
| `debug` | Enable detailed logging during generation |
72+
| Option | Description |
73+
| ---------------------- | ----------------------------------------------------------------------------- |
74+
| `apiDir` | Path to the API directory |
75+
| `schemaDir` | Path to the types/schemas directory |
76+
| `schemaType` | Schema type: `"zod"`, `"typescript"`, or `["zod", "typescript"]` for multiple |
77+
| `schemaFiles` | Optional: Array of custom OpenAPI schema files (YAML/JSON) to include |
78+
| `outputFile` | Name of the OpenAPI output file |
79+
| `outputDir` | Directory where OpenAPI file will be generated (default: `"./public"`) |
80+
| `docsUrl` | API documentation URL (for Swagger UI) |
81+
| `includeOpenApiRoutes` | Whether to include only routes with @openapi tag |
82+
| `ignoreRoutes` | Array of route patterns to exclude from documentation (supports wildcards) |
83+
| `defaultResponseSet` | Default error response set for all endpoints |
84+
| `responseSets` | Named sets of error response codes |
85+
| `errorConfig` | Error schema configuration |
86+
| `debug` | Enable detailed logging during generation |
8887

8988
## Documenting Your API
9089

@@ -766,19 +765,61 @@ export const CreatePostSchema = createInsertSchema(posts, {
766765

767766
See the [complete Drizzle-Zod example](./examples/next15-app-drizzle-zod) for a full working implementation with a blog API.
768767

768+
## Multiple Schema Types Support 🆕
769+
770+
Use **multiple schema types simultaneously** in a single project - perfect for gradual migrations, combining hand-written schemas with generated ones (protobuf, GraphQL), or using existing OpenAPI specs.
771+
772+
### Configuration
773+
774+
```json
775+
{
776+
"schemaType": ["zod", "typescript"],
777+
"schemaDir": "./src/schemas",
778+
"schemaFiles": ["./schemas/external-api.yaml"]
779+
}
780+
```
781+
782+
### Schema Resolution Priority
783+
784+
1. **Custom files** (highest) - from `schemaFiles` array
785+
2. **Zod schemas** (medium) - if `"zod"` in `schemaType`
786+
3. **TypeScript types** (fallback) - if `"typescript"` in `schemaType`
787+
788+
### Common Use Cases
789+
790+
```json
791+
// Gradual TypeScript → Zod migration
792+
{ "schemaType": ["zod", "typescript"] }
793+
794+
// Zod + protobuf schemas
795+
{
796+
"schemaType": ["zod"],
797+
"schemaFiles": ["./proto/schemas.yaml"]
798+
}
799+
800+
// Everything together
801+
{
802+
"schemaType": ["zod", "typescript"],
803+
"schemaFiles": ["./openapi-models.yaml"]
804+
}
805+
```
806+
807+
Custom schema files support YAML/JSON in OpenAPI 3.0 format. See **[next15-app-mixed-schemas](./examples/next15-app-mixed-schemas)** for a complete working example.
808+
769809
## Examples
770810

771811
This repository includes several complete example projects:
772812

773813
### 📦 Available Examples
774814

775-
| Example | Description | Features |
776-
| --------------------------------------------------------------- | -------------------------- | ----------------------------------------------- |
777-
| **[next15-app-zod](./examples/next15-app-zod)** | Zod schemas example | Users, Products, Orders API with Zod validation |
778-
| **[next15-app-drizzle-zod](./examples/next15-app-drizzle-zod)** | Drizzle-Zod integration 🆕 | Blog API with Drizzle ORM + drizzle-zod |
779-
| **[next15-app-typescript](./examples/next15-app-typescript)** | TypeScript types | API with pure TypeScript type definitions |
780-
| **[next15-app-scalar](./examples/next15-app-scalar)** | Scalar UI | Modern API documentation interface |
781-
| **[next15-app-swagger](./examples/next15-app-swagger)** | Swagger UI | Classic Swagger documentation |
815+
| Example | Description | Features |
816+
| --------------------------------------------------------------- | ----------------------- | ----------------------------------------------- |
817+
| **[next15-app-zod](./examples/next15-app-zod)** | Zod schemas example | Users, Products, Orders API with Zod validation |
818+
| **[next15-app-drizzle-zod](./examples/next15-app-drizzle-zod)** | Drizzle-Zod integration | Blog API with Drizzle ORM + drizzle-zod |
819+
| **[next15-app-mixed-schemas](./examples/next15-app-mixed-schemas)** 🆕 | Multiple schema types | Zod + TypeScript + Custom YAML schemas combined |
820+
| **[next15-app-typescript](./examples/next15-app-typescript)** | TypeScript types | API with pure TypeScript type definitions |
821+
| **[next15-app-scalar](./examples/next15-app-scalar)** | Scalar UI | Modern API documentation interface |
822+
| **[next15-app-swagger](./examples/next15-app-swagger)** | Swagger UI | Classic Swagger documentation |
782823

783824
### 🚀 Running Examples
784825

@@ -824,26 +865,11 @@ Visit `http://localhost:3000/api-docs` to see the generated documentation.
824865
</table>
825866
</div>
826867

827-
## Learn More
828-
829-
- **[Drizzle-Zod Example](./examples/next15-app-drizzle-zod)** - Complete example with Drizzle ORM integration
830-
- **[Drizzle ORM](https://orm.drizzle.team/)** - TypeScript ORM for SQL databases
831-
- **[drizzle-zod](https://orm.drizzle.team/docs/zod)** - Zod schema generator for Drizzle
832-
- **[Zod Documentation](https://zod.dev/)** - TypeScript-first schema validation
833-
- **[Next.js Documentation](https://nextjs.org/docs)** - React framework documentation
834-
- **[OpenAPI Specification](https://swagger.io/specification/)** - OpenAPI 3.0 spec
835-
- **[Scalar Documentation](https://docs.scalar.com/)** - Modern API documentation UI
836-
837868
## Contributing
838869

839870
We welcome contributions! 🎉
840871

841-
Please read our [Contributing Guide](CONTRIBUTING.md) for details on:
842-
843-
- 📝 Commit message guidelines (Conventional Commits)
844-
- 🔧 Development setup
845-
- ✅ Pull request process
846-
- 🚀 Release workflow
872+
Please read our [Contributing Guide](CONTRIBUTING.md) for details.
847873

848874
## Changelog
849875

‎examples/next15-app-mixed-schemas/.eslintrc.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"extends": "next/core-web-vitals"
3+
}

‎examples/next15-app-mixed-schemas/.gitignore‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
2+
3+
# dependencies
4+
/node_modules
5+
/.pnp
6+
.pnp.js
7+
8+
# testing
9+
/coverage
10+
11+
# next.js
12+
/.next/
13+
/out/
14+
15+
# production
16+
/build
17+
18+
# misc
19+
.DS_Store
20+
*.pem
21+
22+
# debug
23+
npm-debug.log*
24+
yarn-debug.log*
25+
yarn-error.log*
26+
27+
# local env files
28+
.env*.local
29+
30+
# vercel
31+
.vercel
32+
33+
# typescript
34+
*.tsbuildinfo
35+
next-env.d.ts
36+
37+
# openapi
38+
/public/openapi.json

‎examples/next15-app-mixed-schemas/README.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Mixed Schema Types Example
2+
3+
This example demonstrates using **multiple schema types simultaneously** with next-openapi-gen:
4+
5+
- **Zod schemas** (`src/schemas/zod-schemas.ts`)
6+
- **TypeScript types** (`src/schemas/typescript-types.ts`)
7+
- **Custom OpenAPI YAML files** (`src/schemas/custom-schemas.yaml`)
8+
9+
## Features Demonstrated
10+
11+
### 1. Zod Schemas
12+
13+
- `UserSchema`, `CreateUserSchema`, `UpdateUserSchema`
14+
- `ProductSchema`, `CreateProductSchema`
15+
- Used in `/api/users` and `/api/products` endpoints
16+
17+
### 2. TypeScript Types
18+
19+
- `Order`, `OrderItem`, `OrderStatus`
20+
- `PaginationParams`, `PaginatedResponse<T>`
21+
- Used in `/api/orders` endpoint
22+
23+
### 3. Custom YAML Schemas (from external source, e.g., protobuf)
24+
25+
- `Role`, `Permission`
26+
- `ApiMetadata`
27+
- Used in `/api/roles` and `/api/metadata` endpoints
28+
29+
## Configuration
30+
31+
The `next.openapi.json` config shows how to enable multiple schema types:
32+
33+
```json
34+
{
35+
"schemaType": ["zod", "typescript"],
36+
"schemaFiles": ["./src/schemas/custom-schemas.yaml"],
37+
"schemaDir": "./src/schemas"
38+
}
39+
```
40+
41+
## Priority System
42+
43+
Schemas are resolved with automatic priority:
44+
45+
1. **Custom files** (highest) - from `schemaFiles`
46+
2. **Zod schemas** (medium) - from `schemaDir` with `.ts` extension
47+
3. **TypeScript types** (lowest/fallback) - from `schemaDir` with `.ts` extension
48+
49+
## Getting Started
50+
51+
```bash
52+
# Install dependencies
53+
npm install
54+
55+
# Generate OpenAPI documentation
56+
npm run openapi:generate
57+
58+
# Start development server
59+
npm run dev
60+
```
61+
62+
Then visit:
63+
64+
- **Home**: http://localhost:3000
65+
- **API Docs**: http://localhost:3000/api-docs
66+
- **OpenAPI Spec**: http://localhost:3000/openapi.json
67+
68+
## Use Cases
69+
70+
This setup is perfect for:
71+
72+
- Projects migrating from TypeScript to Zod gradually
73+
- Using external API schemas (protobuf, GraphQL, etc.)
74+
- Combining hand-written and generated schemas
75+
- Large codebases with mixed schema sources

‎examples/next15-app-mixed-schemas/next.config.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
import type { NextConfig } from "next";
2+
3+
const nextConfig: NextConfig = {};
4+
5+
export default nextConfig;

‎examples/next15-app-mixed-schemas/next.openapi.json‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
{
2+
"openapi": "3.0.0",
3+
"info": {
4+
"title": "Mixed Schema Types API",
5+
"version": "1.0.0",
6+
"description": "Example demonstrating Zod + TypeScript + Custom YAML schemas"
7+
},
8+
"servers": [
9+
{
10+
"url": "http://localhost:3000/api",
11+
"description": "Local development server"
12+
}
13+
],
14+
"components": {
15+
"securitySchemes": {
16+
"BearerAuth": {
17+
"type": "http",
18+
"scheme": "bearer",
19+
"bearerFormat": "JWT"
20+
}
21+
}
22+
},
23+
"defaultResponseSet": "common",
24+
"responseSets": {
25+
"common": ["400", "500"]
26+
},
27+
"errorConfig": {
28+
"template": {
29+
"type": "object",
30+
"properties": {
31+
"error": {
32+
"type": "string",
33+
"example": "{{ERROR_MESSAGE}}"
34+
},
35+
"code": {
36+
"type": "string",
37+
"example": "{{ERROR_CODE}}"
38+
}
39+
}
40+
},
41+
"codes": {
42+
"400": {
43+
"description": "Bad Request",
44+
"variables": {
45+
"ERROR_MESSAGE": "Invalid request parameters",
46+
"ERROR_CODE": "BAD_REQUEST"
47+
}
48+
},
49+
"500": {
50+
"description": "Internal Server Error",
51+
"variables": {
52+
"ERROR_MESSAGE": "An unexpected error occurred",
53+
"ERROR_CODE": "INTERNAL_ERROR"
54+
}
55+
}
56+
}
57+
},
58+
"apiDir": "./src/app/api",
59+
"schemaDir": "./src/schemas",
60+
"schemaType": ["zod", "typescript"],
61+
"schemaFiles": ["./src/schemas/custom-schemas.yaml"],
62+
"docsUrl": "api-docs",
63+
"ui": "scalar",
64+
"outputFile": "openapi.json",
65+
"outputDir": "./public",
66+
"includeOpenApiRoutes": false,
67+
"debug": true
68+
}

0 commit comments

Comments
 (0)