@spikers/next-openapi-json-generator 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +211 -0
- package/dist/index.cjs +2074 -0
- package/dist/index.d.cts +18 -0
- package/dist/index.d.ts +18 -0
- package/dist/index.js +2070 -0
- package/package.json +62 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 Omer Mecitoglu
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
# Next OpenAPI JSON Generator
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@omer-x/next-openapi-json-generator)
|
|
4
|
+
[](https://www.npmjs.com/package/@omer-x/next-openapi-json-generator)
|
|
5
|
+
[](https://codecov.io/gh/omermecitoglu/next-openapi-json-generator)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
[](https://github.com/omermecitoglu/next-openapi-json-generator/commits/main/)
|
|
8
|
+
[](https://github.com/omermecitoglu/next-openapi-json-generator/issues)
|
|
9
|
+
[](https://github.com/omermecitoglu/next-openapi-json-generator)
|
|
10
|
+
|
|
11
|
+
## Overview
|
|
12
|
+
|
|
13
|
+
`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.
|
|
14
|
+
|
|
15
|
+
**Key Features:**
|
|
16
|
+
- **Automated OpenAPI Generation**: Automatically generates OpenAPI JSON specs from your route handlers.
|
|
17
|
+
- **TypeScript Integration**: Seamlessly integrates with TypeScript for strong type-checking.
|
|
18
|
+
- **Zod Schema Support**: Uses Zod schemas for validation and generates JSON schemas for OpenAPI.
|
|
19
|
+
- **Next.js Compatibility**: Works seamlessly with Next.js and integrates with other server-side libraries.
|
|
20
|
+
|
|
21
|
+
> **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.
|
|
22
|
+
|
|
23
|
+
## Requirements
|
|
24
|
+
|
|
25
|
+
To use `@omer-x/next-openapi-json-generator`, you'll need the following dependencies in your Next.js project:
|
|
26
|
+
|
|
27
|
+
- [TypeScript](https://www.typescriptlang.org/) >= v5
|
|
28
|
+
- [Next.js](https://nextjs.org/) >= v13
|
|
29
|
+
- [Zod](https://zod.dev/) >= v3
|
|
30
|
+
- [Next OpenAPI Route Handler](https://www.npmjs.com/package/@omer-x/next-openapi-route-handler)
|
|
31
|
+
|
|
32
|
+
## Installation
|
|
33
|
+
|
|
34
|
+
To install this package, along with its peer dependency, run:
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
npm install @omer-x/next-openapi-json-generator @omer-x/next-openapi-route-handler
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Usage
|
|
41
|
+
|
|
42
|
+
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:
|
|
43
|
+
|
|
44
|
+
### Example
|
|
45
|
+
|
|
46
|
+
```typescript
|
|
47
|
+
import generateOpenApiSpec from "@omer-x/next-openapi-json-generator";
|
|
48
|
+
import { NewUserDTO, UserDTO, UserPatchDTO } from "../models/user";
|
|
49
|
+
|
|
50
|
+
const Page = async () => {
|
|
51
|
+
const spec = await generateOpenApiSpec({
|
|
52
|
+
UserDTO,
|
|
53
|
+
NewUserDTO,
|
|
54
|
+
UserPatchDTO,
|
|
55
|
+
}, {
|
|
56
|
+
// options
|
|
57
|
+
});
|
|
58
|
+
return <ReactSwagger spec={spec} />;
|
|
59
|
+
};
|
|
60
|
+
|
|
61
|
+
export default Page;
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Parameters
|
|
65
|
+
|
|
66
|
+
The `generateOpenApiSpec` function takes an object with the following properties:
|
|
67
|
+
|
|
68
|
+
| Property | Type | Description |
|
|
69
|
+
| -------- | ------------------------------------------ | ---------------------------------------------------------------------------------- |
|
|
70
|
+
| models | Record<string, [ZodType](https://zod.dev)> | An object where keys are model names and values are Zod schemas |
|
|
71
|
+
| options | Object | `(Optional)` An object to customize the functionality of the generator (see below) |
|
|
72
|
+
|
|
73
|
+
#### Options
|
|
74
|
+
|
|
75
|
+
| Property | Type | Description |
|
|
76
|
+
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
77
|
+
| include | string[] | `(Optional)` An array of strings which specifies the routes will be included to the JSON output |
|
|
78
|
+
| exclude | string[] | `(Optional)` An array of strings which specifies the routes will be excluded from the JSON output |
|
|
79
|
+
| routeDefinerName | string | `(Optional)` Name of the function that was exported from the [`Next OpenAPI Route Handler`](https://www.npmjs.com/package/@omer-x/next-openapi-route-handler) (Default: `defineRoute`) |
|
|
80
|
+
|
|
81
|
+
### Result
|
|
82
|
+
|
|
83
|
+
The function returns a promise that resolves to an OpenAPI JSON specification.
|
|
84
|
+
|
|
85
|
+
```json
|
|
86
|
+
{
|
|
87
|
+
"openapi": "3.1.0",
|
|
88
|
+
"info": {
|
|
89
|
+
"title": "User Service",
|
|
90
|
+
"version": "1.0.0"
|
|
91
|
+
},
|
|
92
|
+
"paths": {
|
|
93
|
+
"/users": {
|
|
94
|
+
"get": {
|
|
95
|
+
...
|
|
96
|
+
},
|
|
97
|
+
"post": {
|
|
98
|
+
...
|
|
99
|
+
}
|
|
100
|
+
},
|
|
101
|
+
"/users/{id}": {
|
|
102
|
+
"get": {
|
|
103
|
+
"operationId": "getUser",
|
|
104
|
+
"summary": "Get a specific user by ID",
|
|
105
|
+
"description": "Retrieve details of a specific user by their ID",
|
|
106
|
+
"tags": [
|
|
107
|
+
"Users"
|
|
108
|
+
],
|
|
109
|
+
"parameters": [
|
|
110
|
+
{
|
|
111
|
+
"in": "path",
|
|
112
|
+
"name": "id",
|
|
113
|
+
"required": true,
|
|
114
|
+
"description": "ID of the user",
|
|
115
|
+
"schema": {
|
|
116
|
+
"type": "string",
|
|
117
|
+
"description": "ID of the user"
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
],
|
|
121
|
+
"responses": {
|
|
122
|
+
"200": {
|
|
123
|
+
"description": "User details retrieved successfully",
|
|
124
|
+
"content": {
|
|
125
|
+
"application/json": {
|
|
126
|
+
"schema": {
|
|
127
|
+
"$ref": "#/components/schemas/UserDTO"
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
},
|
|
132
|
+
"404": {
|
|
133
|
+
"description": "User not found"
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
},
|
|
137
|
+
"patch": {
|
|
138
|
+
...
|
|
139
|
+
},
|
|
140
|
+
"delete": {
|
|
141
|
+
...
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
},
|
|
145
|
+
"components": {
|
|
146
|
+
"schemas": {
|
|
147
|
+
"UserDTO": {
|
|
148
|
+
"type": "object",
|
|
149
|
+
"properties": {
|
|
150
|
+
"id": {
|
|
151
|
+
"type": "string",
|
|
152
|
+
"format": "uuid",
|
|
153
|
+
"description": "Unique identifier of the user"
|
|
154
|
+
},
|
|
155
|
+
"name": {
|
|
156
|
+
"type": "string",
|
|
157
|
+
"description": "Display name of the user"
|
|
158
|
+
},
|
|
159
|
+
"email": {
|
|
160
|
+
"type": "string",
|
|
161
|
+
"description": "Email address of the user"
|
|
162
|
+
},
|
|
163
|
+
"password": {
|
|
164
|
+
"type": "string",
|
|
165
|
+
"maxLength": 72,
|
|
166
|
+
"description": "Encrypted password of the user"
|
|
167
|
+
},
|
|
168
|
+
"createdAt": {
|
|
169
|
+
"type": "string",
|
|
170
|
+
"format": "date-time",
|
|
171
|
+
"description": "Creation date of the user"
|
|
172
|
+
},
|
|
173
|
+
"updatedAt": {
|
|
174
|
+
"type": "string",
|
|
175
|
+
"format": "date-time",
|
|
176
|
+
"description": "Modification date of the user"
|
|
177
|
+
}
|
|
178
|
+
},
|
|
179
|
+
"required": [
|
|
180
|
+
"id",
|
|
181
|
+
"name",
|
|
182
|
+
"email",
|
|
183
|
+
"password",
|
|
184
|
+
"createdAt",
|
|
185
|
+
"updatedAt"
|
|
186
|
+
],
|
|
187
|
+
"additionalProperties": false,
|
|
188
|
+
"description": "Represents the data of a user in the system."
|
|
189
|
+
},
|
|
190
|
+
"NewUserDTO": {
|
|
191
|
+
...
|
|
192
|
+
},
|
|
193
|
+
"UserPatchDTO": {
|
|
194
|
+
...
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
[An example can be found here](https://github.com/omermecitoglu/example-user-service)
|
|
202
|
+
|
|
203
|
+
## Screenshots
|
|
204
|
+
|
|
205
|
+
| <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> |
|
|
206
|
+
|:--------------:|:--------------:|:--------------:|:--------------:|
|
|
207
|
+
| <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> | |
|
|
208
|
+
|
|
209
|
+
## License
|
|
210
|
+
|
|
211
|
+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
|