Skip to content

Commit 1b189aa

Browse files
MichaelHilusMichaelHilus
committed
Fill readme content and update version
1 parent c36aec4 commit 1b189aa

2 files changed

Lines changed: 242 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 241 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,242 @@
11
# openapi-typescript-client-api-generator
2-
A generator that reads swagger / open api 3 json configs and generates typescript client services with axios
2+
A generator that reads swagger / open api 3 json configs and generates typescript client services with axios.
3+
4+
Hint: implemented with specific use case in mind.
5+
6+
## Example
7+
8+
Your open-api 3 json config file:
9+
```json
10+
{
11+
"openapi": "3.0.1",
12+
"info": {
13+
"title": "Awesome project API",
14+
"description": "The API that is just awesome.",
15+
"version": "1.3.8"
16+
},
17+
"tags" : [ { "name" : "users" } ],
18+
...
19+
"paths": {
20+
"/users": {
21+
"get": {
22+
"tags": [ "users" ],
23+
"operationId": "getAllUsers",
24+
"description": "Gets all users. Can optionally be filtered by group id.",
25+
"parameters": [ {
26+
"name": "groupId",
27+
"in": "query",
28+
"description": "The group of the users to retrieve.",
29+
"required": false,
30+
"schema": {
31+
"type": "integer",
32+
"format": "int32"
33+
}
34+
} ],
35+
"responses": {
36+
"default": {
37+
"description": "The users.",
38+
"content": {
39+
"application/json": {
40+
"schema": {
41+
"type": "array",
42+
"items": {
43+
"$ref" : "#/components/schemas/User"
44+
}
45+
}
46+
}
47+
}
48+
}
49+
}
50+
}
51+
},
52+
"/users/{userId}": {
53+
"get": {
54+
"tags": [ "users" ],
55+
"operationId": "getUserById",
56+
"description": "Retrieve a user by id.",
57+
"parameters": [ {
58+
"name": "userId",
59+
"in": "path",
60+
"description": "The id of the user to retrieve.",
61+
"required": true,
62+
"schema": {
63+
"type": "integer",
64+
"format": "int32"
65+
}
66+
} ],
67+
"responses": {
68+
"default": {
69+
"description": "The user.",
70+
"content": {
71+
"application/json": {
72+
"schema": {
73+
"$ref" : "#/components/schemas/User"
74+
}
75+
}
76+
}
77+
}
78+
}
79+
}
80+
}
81+
},
82+
"components": {
83+
"schemas": {
84+
"User": {
85+
"description": "The user.",
86+
"type": "object",
87+
"properties": {
88+
"id": {
89+
"type": "integer",
90+
"format": "int32",
91+
"description": "The id of the user."
92+
},
93+
"name": {
94+
"type": "string",
95+
"description": "The name of the user."
96+
},
97+
"groupId": {
98+
"type": "integer",
99+
"format": "int32",
100+
"description": "The group id of the user."
101+
}
102+
}
103+
}
104+
}
105+
}
106+
}
107+
```
108+
109+
Generated model ( `user.ts` )
110+
```typescript
111+
/**
112+
* Awesome project API 1.3.8 (OpenAPI: 3.0.1)
113+
* The API that is just awesome.
114+
*
115+
* NOTE: This class is auto generated by openapi-typescript-client-api-generator.
116+
* Do not edit the file manually.
117+
*/
118+
119+
export class User {
120+
121+
/**
122+
* Creates a ListColumn.
123+
*
124+
* @param {number} id The id of the user.
125+
* @param {string} name The name of the user.
126+
* @param {number} groupId The group id of the user.
127+
*/
128+
constructor(id: number, name: string, groupId: number) {
129+
this.id = id;
130+
this.name = name;
131+
this.groupId = groupId;
132+
}
133+
134+
/**
135+
* The id of the user.
136+
*/
137+
public id: number;
138+
139+
/**
140+
* The name of the user.
141+
*/
142+
public name: string;
143+
144+
/**
145+
* The group id of the user.
146+
*/
147+
public group id: number;
148+
}
149+
```
150+
151+
Generated service ( `usersService.ts` )
152+
```typescript
153+
/**
154+
* Awesome project API 1.3.8 (OpenAPI: 3.0.1)
155+
* The API that is just awesome.
156+
*
157+
* NOTE: This class is auto generated by openapi-typescript-client-api-generator.
158+
* Do not edit the file manually.
159+
*/
160+
161+
import axios from "axios";
162+
163+
import { ServiceBase } from "../../services/serviceBase";
164+
import { IUsersService } from "./usersService.interface";
165+
166+
import { User } from "../models/user";
167+
168+
export class UsersService extends ServiceBase implements IUsersService {
169+
/**
170+
* Gets all users. Can optionally be filtered by group id.
171+
*
172+
* @param {number} [groupId] The group of the users to retrieve.
173+
*/
174+
public async getAllUsers(groupId?: number): Promise<User[]> {
175+
const config = this.getAxiosConfiguration();
176+
177+
const queryList: string[] = [];
178+
if (groupId !== undefined) {
179+
queryList.push(`groupId=${groupId}`);
180+
}
181+
const query = `?${queryList.join("&")}`;
182+
183+
const response = await axios.get<User[]>(`/users${query}`, config);
184+
return response.data;
185+
}
186+
187+
/**
188+
* Retrieve a user by id..
189+
*
190+
* @param {number} userId The id of the user to retrieve.
191+
*/
192+
public async getUserById(userId?: number): Promise<User[]> {
193+
const config = this.getAxiosConfiguration();
194+
195+
const response = await axios.get<User[]>(`/users/${userId}`, config);
196+
return response.data;
197+
}
198+
}
199+
```
200+
201+
## Installation
202+
```shell
203+
$ yarn add @progresso/openapi-typescript-client-api-generator --dev
204+
```
205+
206+
## Usage
207+
208+
### Add an open-api 2.0 / 3.x file to your project
209+
Add a swagger (open-api 2.0) or open-api 3 json config file into your project. I.e. at
210+
`[project-root]/api/awesone-api.json`
211+
212+
### Configure scripts section in package.json
213+
Add a script line into your `package.json`:
214+
```json
215+
{
216+
...
217+
"scripts": {
218+
"generate": "openapi-typescript-client-api-generator"
219+
}
220+
}
221+
```
222+
### Implement ServiceBase for request headers
223+
Implement a service base class called `ServiceBase` that implements the following method so you are able to pass custom headers like authentication tokens to your requests:
224+
```typescript
225+
protected getAxiosConfiguration(): AxiosRequestConfig
226+
```
227+
228+
### Run the generator
229+
Execute the generator with
230+
```shell
231+
$ yarn generate -c /api/awesome-api.json -sb /client/services -s /client/api/services -m /client/api/models -sm /server/modules/api/models
232+
```
233+
234+
## Parameter documentation
235+
All parameters are required currently. All pathes are relative to the project root.
236+
| Parameter | Description | Example |
237+
|--------------|-----------------------------------------------------------------------------------------------------------|-------------------------|
238+
| `-c <path>` | The path to your json config file. | `/api/awesome-api.json` |
239+
| `-sb <path>` | The path to the directory where your `ServiceBase` class is located. | `/client/services` |
240+
| `-s <path>` | The path to the directory where the generated services should be saved to. Will be created if neccessary. | `/client/api/services` |
241+
| `-m <path>` | The path to the directory where the generated models should be saved to. Will be created if neccessary. | `/client/api/models` |
242+
| `-sm <path>` | The path to a directory that contains server side models decorated for `@nestjs/swagger` generation. Used when the config file's version is 2.0 (swagger) to augment services and models by inheritance information. Not used when config file's version is >= 3.0.0 (open-api 3). | `/server/modules/api/models` |

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "@progresso/openapi-typescript-client-api-generator",
33
"description": "A generator that reads swagger / open api 3 json configs and generates typescript client services with axios",
4-
"version": "1.0.0",
4+
"version": "1.0.1",
55
"main": "index.js",
66
"repository": {
77
"type": "git",

0 commit comments

Comments
 (0)