Skip to content

Commit 84db1e4

Browse files
omermecitogluomermecitoglu
committed
add readme
1 parent 700f3ba commit 84db1e4

File tree

2 files changed

+214
-0
lines changed

2 files changed

+214
-0
lines changed

‎.github/workflows/npm-publish.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: Publish Package to npm
2+
on:
3+
release:
4+
types: [published]
5+
jobs:
6+
build:
7+
runs-on: ubuntu-latest
8+
steps:
9+
- uses: actions/checkout@v4
10+
- uses: actions/setup-node@v4
11+
with:
12+
node-version: '20.x'
13+
registry-url: 'https://registry.npmjs.org'
14+
- run: npm ci
15+
# - run: npm test
16+
- run: npm run build
17+
- run: npm publish
18+
env:
19+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎README.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Next OpenAPI JSON Generator
2+
3+
[![npm version](https://badge.fury.io/js/%40omer-x%2Fnext-openapi-json-generator.svg)](https://badge.fury.io/js/%40omer-x%2Fnext-openapi-json-generator)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5+
6+
## Overview
7+
8+
`Next OpenAPI JSON Generator` is an open-source Next.js plugin that extracts and generates OpenAPI JSON specifications from your route handlers defined using `@omer-x/next-openapi-route-handler`. It simplifies the process of generating and maintaining OpenAPI documentation by leveraging TypeScript and Zod schemas.
9+
10+
**Key Features:**
11+
- **Automated OpenAPI Generation**: Automatically generates OpenAPI JSON specs from your route handlers.
12+
- **TypeScript Integration**: Seamlessly integrates with TypeScript for strong type-checking.
13+
- **Zod Schema Support**: Uses Zod schemas for validation and generates JSON schemas for OpenAPI.
14+
- **Next.js Compatibility**: Works seamlessly with Next.js and integrates with other server-side libraries.
15+
16+
> **Note:** This package works in conjunction with [`Next OpenAPI Route Handler`](https://www.npmjs.com/package/@omer-x/next-openapi-route-handler) to extract the generated OpenAPI JSON.
17+
18+
## Requirements
19+
20+
To use `@omer-x/next-openapi-json-generator`, you'll need the following dependencies in your Next.js project:
21+
22+
- [TypeScript](https://www.typescriptlang.org/) >= v5
23+
- [Next.js](https://nextjs.org/) >= v13
24+
- [Zod](https://zod.dev/) >= v3
25+
- [Next OpenAPI Route Handler](https://www.npmjs.com/package/@omer-x/next-openapi-route-handler)
26+
27+
## Installation
28+
29+
To install this package, along with its peer dependency, run:
30+
31+
```sh
32+
npm install @omer-x/next-openapi-json-generator @omer-x/next-openapi-route-handler
33+
```
34+
35+
## Usage
36+
37+
The `generateOpenApiSpec` function is used to extract and generate the OpenAPI JSON specification from your defined models. Here's a description of how to use it:
38+
39+
### Example
40+
41+
```typescript
42+
import generateOpenApiSpec from "@omer-x/next-openapi-json-generator";
43+
import { NewUserDTO, UserDTO, UserPatchDTO } from "../models/user";
44+
45+
const Page = async () => {
46+
const spec = await generateOpenApiSpec({
47+
UserDTO,
48+
NewUserDTO,
49+
UserPatchDTO,
50+
});
51+
return <ReactSwagger spec={spec} />;
52+
};
53+
54+
export default Page;
55+
```
56+
57+
### Parameters
58+
59+
The `generateOpenApiSpec` function takes an object with the following properties:
60+
61+
| Property | Type | Description |
62+
| ------------ | ------------------------------------------- | ---------------------------------------------------------------- |
63+
| models | Record<string, [ZodType](https://zod.dev)> | An object where keys are model names and values are Zod schemas. |
64+
65+
### Result
66+
67+
The function returns a promise that resolves to an OpenAPI JSON specification.
68+
69+
```json
70+
{
71+
"openapi": "3.1.0",
72+
"info": {
73+
"title": "User Service",
74+
"version": "1.0.0"
75+
},
76+
"paths": {
77+
"/users": {
78+
"get": {
79+
...
80+
},
81+
"post": {
82+
...
83+
}
84+
},
85+
"/users/{id}": {
86+
"get": {
87+
"operationId": "getUser",
88+
"summary": "Get a specific user by ID",
89+
"description": "Retrieve details of a specific user by their ID",
90+
"tags": [
91+
"Users"
92+
],
93+
"parameters": [
94+
{
95+
"in": "path",
96+
"name": "id",
97+
"required": true,
98+
"description": "ID of the user",
99+
"schema": {
100+
"type": "string",
101+
"description": "ID of the user"
102+
}
103+
}
104+
],
105+
"responses": {
106+
"200": {
107+
"description": "User details retrieved successfully",
108+
"content": {
109+
"application/json": {
110+
"schema": {
111+
"$ref": "#/components/schemas/UserDTO"
112+
}
113+
}
114+
}
115+
},
116+
"404": {
117+
"description": "User not found"
118+
}
119+
}
120+
},
121+
"patch": {
122+
...
123+
},
124+
"delete": {
125+
...
126+
}
127+
}
128+
},
129+
"components": {
130+
"schemas": {
131+
"UserDTO": {
132+
"type": "object",
133+
"properties": {
134+
"id": {
135+
"type": "string",
136+
"format": "uuid",
137+
"description": "Unique identifier of the user"
138+
},
139+
"name": {
140+
"type": "string",
141+
"description": "Display name of the user"
142+
},
143+
"email": {
144+
"type": "string",
145+
"description": "Email address of the user"
146+
},
147+
"password": {
148+
"type": "string",
149+
"maxLength": 72,
150+
"description": "Encrypted password of the user"
151+
},
152+
"createdAt": {
153+
"type": "string",
154+
"format": "date-time",
155+
"description": "Creation date of the user"
156+
},
157+
"updatedAt": {
158+
"type": "string",
159+
"format": "date-time",
160+
"description": "Modification date of the user"
161+
}
162+
},
163+
"required": [
164+
"id",
165+
"name",
166+
"email",
167+
"password",
168+
"createdAt",
169+
"updatedAt"
170+
],
171+
"additionalProperties": false,
172+
"description": "Represents the data of a user in the system."
173+
},
174+
"NewUserDTO": {
175+
...
176+
},
177+
"UserPatchDTO": {
178+
...
179+
}
180+
}
181+
}
182+
}
183+
```
184+
185+
[An example can be found here](https://github.com/omermecitoglu/example-user-service)
186+
187+
## Screenshots
188+
189+
| <a href="https://i.imgur.com/ru3muBc.png" target="_blank"><img src="https://i.imgur.com/ru3muBc.png" alt="screenshot-1"></a> | <a href="https://i.imgur.com/utHaZ6X.png" target="_blank"><img src="https://i.imgur.com/utHaZ6X.png" alt="screenshot-2"></a> | <a href="https://i.imgur.com/2f24kPE.png" target="_blank"><img src="https://i.imgur.com/2f24kPE.png" alt="screenshot-3"></a> | <a href="https://i.imgur.com/z3KIJQ1.png" target="_blank"><img src="https://i.imgur.com/z3KIJQ1.png" alt="screenshot-4"></a> |
190+
|:--------------:|:--------------:|:--------------:|:--------------:|
191+
| <a href="https://i.imgur.com/IFKXOiX.png" target="_blank"><img src="https://i.imgur.com/IFKXOiX.png" alt="screenshot-5"></a> | <a href="https://i.imgur.com/xzVjAPq.png" target="_blank"><img src="https://i.imgur.com/xzVjAPq.png" alt="screenshot-6"></a> | <a href="https://i.imgur.com/HrWuHOR.png" target="_blank"><img src="https://i.imgur.com/HrWuHOR.png" alt="screenshot-7"></a> | |
192+
193+
## License
194+
195+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)