Skip to content

Commit bd37bdf

Browse files
omermecitogluomermecitoglu
committed
update readme
1 parent ffd7139 commit bd37bdf

File tree

2 files changed

+134
-143
lines changed

2 files changed

+134
-143
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: 115 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -14,16 +14,15 @@
1414
- **Integration with Next.js**: Works seamlessly with Next.js App Directory features.
1515
- **Customizable**: Compatible with existing Next.js projects and fully customizable to suit your needs.
1616

17-
> **Note:** This package has a peer dependency on [`Next OpenAPI.json Generator`](https://www.npmjs.com/package/@omer-x/next-openapi-json-generator) for extracting the generated OpenAPI JSON.
17+
> **Note:** This package has a peer dependency on [`Next OpenAPI JSON Generator`](https://www.npmjs.com/package/@omer-x/next-openapi-json-generator) for extracting the generated OpenAPI JSON.
1818
1919
## Requirements
2020

2121
To use `@omer-x/next-openapi-route-handler`, you'll need the following dependencies in your Next.js project:
2222

2323
- [Next.js](https://nextjs.org/) >= v13
24-
- [TypeScript](https://www.typescriptlang.org/) >= v5
2524
- [Zod](https://zod.dev/) >= v3
26-
- [Next OpenAPI.json Generator](https://www.npmjs.com/package/@omer-x/next-openapi-json-generator)
25+
- [Next OpenAPI JSON Generator](https://www.npmjs.com/package/@omer-x/next-openapi-json-generator)
2726

2827
## Installation
2928

@@ -37,18 +36,34 @@ npm install @omer-x/next-openapi-route-handler @omer-x/next-openapi-json-generat
3736

3837
The `createRoute` function is used to define route handlers in a type-safe and self-documenting way. Below is a description of each property of the input parameter:
3938

40-
| Property | Type | Description |
41-
| ------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
42-
| operationId | `string` | Unique identifier for the operation. |
43-
| method | `HttpMethod` | HTTP method for the route (e.g., GET, POST, PUT, PATCH, DELETE). |
44-
| summary | `string` | Short summary of the operation. |
45-
| description | `string` | Detailed description of the operation. |
46-
| tags | `string[]` | Tags for categorizing the operation. |
47-
| pathParams | `ZodType` | Zod schema for validating path parameters. |
48-
| queryParams | `ZodType` | Zod schema for validating query parameters. |
49-
| requestBody | `ZodType` | Zod schema for the request body (required for POST/PUT/PATCH). |
50-
| action | `({ pathParams, queryParams, body }) => Promise<Response>` | Function handling the request, receiving pathParams, queryParams, and requestBody. |
51-
| responses | `Record<string, ResponseDefinition>` | Object defining possible responses, each with a description and optional content schema. |
39+
| Property | Type | Description |
40+
| ------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
41+
| operationId | `string` | Unique identifier for the operation. |
42+
| method | `string` | HTTP method for the route (e.g., `GET`, `POST`, `PUT`, `PATCH`, `DELETE`). |
43+
| summary | `string` | Short summary of the operation. |
44+
| description | `string` | Detailed description of the operation. |
45+
| tags | `string[]` | Tags for categorizing the operation. |
46+
| pathParams | [ZodType](https://zod.dev) | `(Optional)` Zod schema for validating path parameters. |
47+
| queryParams | [ZodType](https://zod.dev) | `(Optional)` Zod schema for validating query parameters. |
48+
| requestBody | [ZodType](https://zod.dev) | Zod schema for the request body (required for `POST`, `PUT`, `PATCH`). |
49+
| action | (source: [ActionSource](#action-source)) => Promise<[Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)> | Function handling the request, receiving pathParams, queryParams, and requestBody. |
50+
| responses | Record<`number`, [ResponseDefinition](#response-definition)> | Object defining possible responses, each with a description and optional content schema. |
51+
52+
### Action Source
53+
54+
| Property | Type | Description |
55+
| ------------- | --------------------------- | -------------------------------------------- |
56+
| pathParams | [ZodType](https://zod.dev) | Parsed parameters from the request URL path. |
57+
| queryParams | [ZodType](https://zod.dev) | Parsed parameters from the request query. |
58+
| body | [ZodType](https://zod.dev) | Parsed request body. |
59+
60+
### Response Definition
61+
62+
| Property | Type | Description |
63+
| ------------- | --------------------------- | ---------------------------------------------- |
64+
| description | `string` | Description of the response. |
65+
| content | [ZodType](https://zod.dev) | `(Optional)` Zod schema for the response body. |
66+
| isArray | `boolean` | `(Optional)` Is the content an array? |
5267

5368
## Example
5469

@@ -62,67 +77,19 @@ export const { GET } = createRoute({
6277
operationId: "getUser",
6378
method: "GET",
6479
summary: "Get a specific user by ID",
65-
description: "Retrieve detailed information about a user by their unique ID",
80+
description: "Retrieve details of a specific user by their ID",
6681
tags: ["Users"],
6782
pathParams: z.object({
6883
id: z.string().describe("ID of the user"),
6984
}),
70-
action: ({ pathParams }) => {
71-
const userId = pathParams.id;
72-
// do something with userId
73-
return Response.json(userId);
85+
action: async ({ pathParams }) => {
86+
const results = await db.select().from(users).where(eq(users.id, pathParams.id));
87+
const user = results.shift();
88+
if (!user) return new Response(null, { status: 404 });
89+
return Response.json(user);
7490
},
7591
responses: {
76-
200: {
77-
description: "Successful response",
78-
content: z.object({
79-
id: z.string().uuid(),
80-
name: z.string().min(1),
81-
email: z.string().email(),
82-
createdAt: z.date(),
83-
}),
84-
},
85-
404: { description: "User not found" },
86-
},
87-
});
88-
89-
export const { PATCH } = createRoute({
90-
operationId: "updateUser",
91-
method: "PATCH",
92-
summary: "Update a specific user by ID",
93-
description: "Update the details of an existing user identified by their unique ID",
94-
tags: ["Users"],
95-
pathParams: z.object({
96-
id: z.string().describe("ID of the user"),
97-
}),
98-
action: ({ pathParams }) => {
99-
const userId = pathParams.id;
100-
// do something with userId
101-
return Response.json(userId);
102-
},
103-
responses: {
104-
200: { description: "User updated successfully" },
105-
404: { description: "User not found" },
106-
409: { description: "Email already exists" },
107-
},
108-
});
109-
110-
export const { DELETE } = createRoute({
111-
operationId: "deleteUser",
112-
method: "DELETE",
113-
summary: "Delete a specific user by ID",
114-
description: "Remove a user from the system by their unique ID",
115-
tags: ["Users"],
116-
pathParams: z.object({
117-
id: z.string().describe("ID of the user"),
118-
}),
119-
action: ({ pathParams }) => {
120-
const userId = pathParams.id;
121-
// do something with userId
122-
return Response.json(userId);
123-
},
124-
responses: {
125-
204: { description: "User deleted successfully" },
92+
200: { description: "User details retrieved successfully", content: UserDTO },
12693
404: { description: "User not found" },
12794
},
12895
});
@@ -138,50 +105,41 @@ This will generate an OpenAPI JSON like this:
138105
"version": "1.0.0"
139106
},
140107
"paths": {
108+
"/users": {
109+
"get": {
110+
...
111+
},
112+
"post": {
113+
...
114+
}
115+
},
141116
"/users/{id}": {
142117
"get": {
143118
"operationId": "getUser",
144119
"summary": "Get a specific user by ID",
145-
"description": "Retrieve detailed information about a user by their unique ID",
146-
"tags": ["Users"],
120+
"description": "Retrieve details of a specific user by their ID",
121+
"tags": [
122+
"Users"
123+
],
147124
"parameters": [
148125
{
149126
"in": "path",
150127
"name": "id",
151128
"required": true,
152129
"description": "ID of the user",
153130
"schema": {
154-
"type": "string"
131+
"type": "string",
132+
"description": "ID of the user"
155133
}
156134
}
157135
],
158136
"responses": {
159137
"200": {
160-
"description": "Successful response",
138+
"description": "User details retrieved successfully",
161139
"content": {
162140
"application/json": {
163141
"schema": {
164-
"type": "object",
165-
"properties": {
166-
"id": {
167-
"type": "string",
168-
"format": "uuid"
169-
},
170-
"name": {
171-
"type": "string",
172-
"minLength": 1
173-
},
174-
"email": {
175-
"type": "string",
176-
"format": "email"
177-
},
178-
"createdAt": {
179-
"type": "string",
180-
"format": "date-time"
181-
}
182-
},
183-
"required": ["id", "name", "email", "createdAt"],
184-
"additionalProperties": false
142+
"$ref": "#/components/schemas/UserDTO"
185143
}
186144
}
187145
}
@@ -192,64 +150,78 @@ This will generate an OpenAPI JSON like this:
192150
}
193151
},
194152
"patch": {
195-
"operationId": "updateUser",
196-
"summary": "Update a specific user by ID",
197-
"description": "Update the details of an existing user identified by their unique ID",
198-
"tags": ["Users"],
199-
"parameters": [
200-
{
201-
"in": "path",
202-
"name": "id",
203-
"required": true,
204-
"description": "ID of the user",
205-
"schema": {
206-
"type": "string"
207-
}
208-
}
209-
],
210-
"responses": {
211-
"200": {
212-
"description": "User updated successfully"
213-
},
214-
"404": {
215-
"description": "User not found"
216-
},
217-
"409": {
218-
"description": "Email already exists"
219-
}
220-
}
153+
...
221154
},
222155
"delete": {
223-
"operationId": "deleteUser",
224-
"summary": "Delete a specific user by ID",
225-
"description": "Remove a user from the system by their unique ID",
226-
"tags": ["Users"],
227-
"parameters": [
228-
{
229-
"in": "path",
230-
"name": "id",
231-
"required": true,
232-
"description": "ID of the user",
233-
"schema": {
234-
"type": "string"
235-
}
236-
}
237-
],
238-
"responses": {
239-
"204": {
240-
"description": "User deleted successfully"
156+
...
157+
}
158+
}
159+
},
160+
"components": {
161+
"schemas": {
162+
"UserDTO": {
163+
"type": "object",
164+
"properties": {
165+
"id": {
166+
"type": "string",
167+
"format": "uuid",
168+
"description": "Unique identifier of the user"
241169
},
242-
"404": {
243-
"description": "User not found"
170+
"name": {
171+
"type": "string",
172+
"description": "Display name of the user"
173+
},
174+
"email": {
175+
"type": "string",
176+
"description": "Email address of the user"
177+
},
178+
"password": {
179+
"type": "string",
180+
"maxLength": 72,
181+
"description": "Encrypted password of the user"
182+
},
183+
"createdAt": {
184+
"type": "string",
185+
"format": "date-time",
186+
"description": "Creation date of the user"
187+
},
188+
"updatedAt": {
189+
"type": "string",
190+
"format": "date-time",
191+
"description": "Modification date of the user"
244192
}
245-
}
193+
},
194+
"required": [
195+
"id",
196+
"name",
197+
"email",
198+
"password",
199+
"createdAt",
200+
"updatedAt"
201+
],
202+
"additionalProperties": false,
203+
"description": "Represents the data of a user in the system."
204+
},
205+
"NewUserDTO": {
206+
...
207+
},
208+
"UserPatchDTO": {
209+
...
246210
}
247211
}
248212
}
249213
}
250214
```
251215

252-
> **Important:** This package cannot extract the OpenAPI JSON by itself. Use [Next OpenAPI.json Generator](https://www.npmjs.com/package/@omer-x/next-openapi-json-generator) to extract the generated data as JSON.
216+
> **Important:** This package cannot extract the OpenAPI JSON by itself. Use [Next OpenAPI JSON Generator](https://www.npmjs.com/package/@omer-x/next-openapi-json-generator) to extract the generated data as JSON.
217+
218+
[An example can be found here](https://github.com/omermecitoglu/example-user-service)
219+
220+
## Screenshots
221+
222+
| <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> |
223+
|:--------------:|:--------------:|:--------------:|:--------------:|
224+
| <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> | |
253225

254226
## License
255227

0 commit comments

Comments
 (0)