1 | [![NPM](https://nodei.co/npm/swagger-typescript.png)](https://nodei.co/npm/swagger-typescript/)
|
2 |
|
3 | [![install size](https://packagephobia.now.sh/badge?p=swagger-typescript)](https://packagephobia.now.sh/result?p=swagger-typescript) [![dependencies](https://david-dm.org/hosseinmd/swagger-typescript.svg)](https://david-dm.org/hosseinmd/swagger-typescript.svg)
|
4 |
|
5 | :star::star::star: If you would like to contribute, please refer to [To do list](https://github.com/hosseinmd/swagger-typescript/projects/1) and a list of [open tasks](https://github.com/hosseinmd/swagger-typescript/issues?q=is%3Aopen).:star::star::star:
|
6 |
|
7 | # Swagger-Typescript: Generate ts/js code from swagger/openApi JSON
|
8 |
|
9 | Support OpenApi v3 and swagger v2
|
10 |
|
11 | An auto typescript/javascript code generator from swagger.
|
12 | Each endpoint will be created as a function, full type base.
|
13 | Supported
|
14 |
|
15 | - Generating a function for every apis
|
16 | - Generating all types, interfaces and enums which used in apis
|
17 | - React hooks.
|
18 | - SignalR hub.
|
19 | - Generating mock data.
|
20 |
|
21 | For Example:
|
22 | Get method of '/Account' path will be this code in services.ts
|
23 |
|
24 | ```js
|
25 | import { getAccount } from "./services";
|
26 |
|
27 | const response = await getAccount({ id: 1234 });
|
28 | ```
|
29 |
|
30 | ## install
|
31 |
|
32 | `$ yarn add swagger-typescript`
|
33 |
|
34 | ## get start
|
35 |
|
36 | Before running, add your config to swagger.config.json
|
37 |
|
38 | #### swagger.config.json
|
39 |
|
40 | ```json
|
41 | {
|
42 | "url": "http://example.com/api/swagger.json",
|
43 | "dir": "./services",
|
44 | "prefix": "/api"
|
45 | }
|
46 | ```
|
47 |
|
48 | #### run
|
49 |
|
50 | ```
|
51 | yarn swag-ts
|
52 | ```
|
53 |
|
54 | #### config.ts
|
55 |
|
56 | [more](#config)
|
57 |
|
58 | baseConfig
|
59 |
|
60 | ```ts
|
61 | const baseConfig: AxiosRequestConfig = {
|
62 | baseURL: "", // <--- Add your base url
|
63 | //other static configs
|
64 | };
|
65 | ```
|
66 |
|
67 | Now you can use APIs, So for advanced config read below.
|
68 |
|
69 | ## swagger.config.json
|
70 |
|
71 | For Example:
|
72 |
|
73 | ```json
|
74 | {
|
75 | "url": "http://example.com/api/swagger.json",
|
76 | "dir": "./services",
|
77 | "prettierPath": ".prettierrc",
|
78 | "language": "typescript"
|
79 | }
|
80 | ```
|
81 |
|
82 | | [`Key`] | [`default`] | Comment |
|
83 | | -------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
84 | | `url` | Required | Address of swagger.json |
|
85 | | `dir` | Required | Address of output |
|
86 | | `language` | `typescript` | export to "javascript" or "typescript" |
|
87 | | `methodName` | `{method}{path}` | Supported mixed of "{method}{path}{operationId}". for Example: 'service{method}{path}' |
|
88 | | `prefix` | Optional | prefix value will be removed from method name For example your endpoints is like "/api/v2/users", If you don't want add "/api/v2" to method name, add it to prefix |
|
89 | | `ignore` | Optional | Ignore headers from type for Example: `"ignore": { "headerParams": ["terminalId"]}` |
|
90 | | `methodParamsByTag` | false | add add a tag insteadOf params name to generated method name (example: getUserP1P2 insteadOf getUserConnectionIdAccountId) |
|
91 | | `mock` | false | For generate response mocks |
|
92 | | `keepJson` | false | This code will keep previous JSON for updating partially. change it to true then generate service for creating your first json file then you can update a tag for example `$ yarn swag-ts User` will update your user APIs which have User tag |
|
93 | | `reactHooks` | false | For generate react hooks of all APIs (using react-query under the hood) |
|
94 | | `useQuery` | [] | List of apis which is get but developed with post methods (Is useful for rest apis) for Example: ["postTicketsGetall"] (Needed to enable `reactHooks`) |
|
95 | | `useInfiniteQuery` | [] | List of apis which is get and could be handle infinity (Needed to enable `reactHooks`) parameter should be one of `page`, `pageNo` or `pageNumber` |
|
96 | | `local` | false | update swagger with local swagger.json located in your dir folder. add it to your config file or run it with cli `$ yarn swag-ts --local` |
|
97 | | `generateEnumAsType` | false |
|
98 |
|
99 | - `enum ReferralStatus {Successed="Successed","Error"="Error"} `
|
100 | - `type ReferralStatus="Successed" | "Error"; // generateEnumAsType = true `
|
101 | |
|
102 |
|
103 | ## Config
|
104 |
|
105 |
|
106 | The config.ts file automatically will be created after first run. You could change this file for customization. Don't change other files, if you want another config create Issue or PR.
|
107 |
|
108 | - getAxiosInstance
|
109 |
|
110 | getAxiosInstance used for create an instance of axios request you can customize that for what you needed
|
111 |
|
112 | - baseConfig
|
113 |
|
114 | baseConfig used for get static configs and headers. if you need some dynamic configs like add authentication to headers use `requestConfig.headers.authorization` into of `axiosInstance.interceptors.request.use` function.
|
115 |
|
116 | ## run by node
|
117 |
|
118 | ```js
|
119 | const { generate } = require("swagger-typescript");
|
120 |
|
121 | generate(config);
|
122 | // or
|
123 | generate(); // will be use ./swagger.config.json
|
124 | ```
|
125 |
|
126 | ## Conflict
|
127 |
|
128 | In some situation teams have parallel backend development which cause conflict when updating swagger for solving this we have partially update, you can update your service just for a few tags and keep other old services codes.
|
129 |
|
130 | For Doing this you need to add this to your swagger.config.json
|
131 |
|
132 | ```
|
133 | "keepJson": true,
|
134 | ```
|
135 |
|
136 | This code will keep previous JSON for updating partially.
|
137 |
|
138 | Run `$ yarn swag-ts` with your base backend, for example develop branch
|
139 |
|
140 | Others need to pull this changes
|
141 |
|
142 | Now you can update Tag1 and Tag2 `$ yarn swag-ts Tag1 Tag2`.
|
143 |
|
144 | ## Multiple-Gateway
|
145 |
|
146 | ## swagger.config.json
|
147 |
|
148 | swagger.config.json
|
149 |
|
150 | ```json
|
151 | [
|
152 | {
|
153 | "url": "http://example1.com/api/swagger.json",
|
154 | "dir": "./service1",
|
155 | "prettierPath": ".prettierrc",
|
156 | "language": "typescript"
|
157 | },
|
158 | {
|
159 | "url": "http://example2.com/api/swagger.json",
|
160 | "dir": "./service2",
|
161 | "prettierPath": ".prettierrc",
|
162 | "language": "typescript"
|
163 | }
|
164 | ]
|
165 | ```
|
166 |
|
167 | ## Stories
|
168 |
|
169 | [why-you-should-use-swagger-typescript-for-generate-apis-code](https://medium.com/@hosseinm.developer/why-you-should-use-swagger-typescript-for-generate-apis-code-63eb8623fef8?source=friends_link&sk=2aa0e2d30b3be158d18c1feb4e12d4a6)
|