You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Generate ES6 or Typescript code from an OpenAPI 2.0 spec, so that accessing REST API resources from the client code is less error-prone, static-typed and just easier to use long-term.
16
+
Generate ES6 or Typescript code from an OpenAPI 3.0 spec, so that accessing REST API resources from the client code is less error-prone, static-typed and just easier to use long-term.
17
17
18
18
You can take a look at the [Examples section](#example) down below.
19
19
@@ -29,29 +29,43 @@ Or globally to run CLI from anywhere
29
29
30
30
npm install swaggie -g
31
31
32
+
## OpenAPI versions
33
+
34
+
Swaggie from version 1.0 supports OpenAPI 3.0 (and some features of 3.1). Swagger or OpenAPI v2 documents are not supported anymore, but you have few options how to deal with it:
35
+
36
+
-**(preferred)** From your backend server generate OpenAPI 3.0 spec instead of version 2 (samples are updated to use OpenAPI 3.0)
37
+
- Convert your OpenAPI 2.0 spec to 3.0 using [swagger2openapi](https://www.npmjs.com/package/swagger2openapi) tool (or something similar)
38
+
- If you can't do that for any reason, you can stick to `Swaggie v0.x`. But upgrade is suggested
39
+
40
+
Please note that OpenAPI 3.0 is a major spec upgrade and it's possible that there will be some breaking changes in the generated code.
41
+
I have tried my best to minimize the impact, but it was not possible to avoid it completely.
42
+
43
+
More info about breaking changes can be found in the [Releases](https://github.com/yhnavein/swaggie/releases).
44
+
32
45
### CLI
33
46
34
47
```
35
48
Usage: swaggie [options]
36
49
37
50
Options:
38
51
39
-
-h, --help output usage information
40
-
-V, --version output the version number
41
-
-c, --config <path> The path to the configuration JSON file. You can do all the set up there instead of parameters in the CLI
42
-
-s, --src <url|path> The url or path to the Open API spec file
43
-
-t, --template <string> Template used forgenerating API client. Default: "axios"
44
-
-o, --out <path> The path to the file where the API would be generated
45
-
-b, --baseUrl <string> Base URL that will be used as a default value in the clients. Default: ""
46
-
--preferAny Use "any" type instead of "unknown". Default: false
47
-
--servicePrefix <string> Prefix for service names. Useful when you have multiple APIs and you want to avoid name collisions. Default: ''
48
-
--queryModels <bool> Generate models for query string instead list of parameters. Default: false
52
+
-V, --version output the version number
53
+
-c, --config <path> The path to the configuration JSON file. You can do all the set up there instead of parameters in the CLI
54
+
-s, --src <url|path> The url or path to the Open API spec file
55
+
-o, --out <filePath> The path to the file where the API would be generated. Use stdout if left empty
56
+
-b, --baseUrl <string> Base URL that will be used as a default value in the clients (default: "")
57
+
-t, --template <string> Template used forgenerating API client. Default: "axios"
58
+
--preferAny Use "any" type instead of "unknown" (default: false)
59
+
--servicePrefix <string> Prefix for service names. Useful when you have multiple APIs and you want to avoid name collisions (default: "")
60
+
--allowDots <bool> Determines if dots should be used for serialization object properties
61
+
--arrayFormat <format> Determines how arrays should be serialized (choices: "indices", "repeat", "brackets")
`swaggie` outputs TypeScript that is somehow formatted, but it's far from perfect. You can adjust the generated code by prettifying output using your preferred beautify tool using your repo's styling guidelines. For example involving `prettier` looks like this:
@@ -72,13 +86,16 @@ Sample configuration looks like this:
Let's assume that you have a [PetStore API](http://petstore.swagger.io/) as your REST API and you are developing a client app written in TypeScript that will consume this API.
114
124
115
-
function complete(spec) {
116
-
console.info('Service generation complete');
117
-
}
125
+
Instead of writing any code by hand for fetching particular resources, we will let Swaggie do it for us.
118
126
119
-
function error(e) {
120
-
console.error(e.toString());
121
-
}
122
-
```
127
+
### Query Parameters Serialization
123
128
124
-
## Usage – Integrating into your project
129
+
When it comes to use of query parameters then you might need to adjust the way these parameters will be serialized, as backend server you are using expects them to be in a specific format. Thankfully in Swaggie you can specify how they should be handled. If you won't provide any configuration, then Swaggie will use the defaults values expected in the ASP.NET Core world.
125
130
126
-
Let's assume that you have a [PetStore API](http://petstore.swagger.io/) as your REST API and you are developing a client app written in TypeScript that will consume this API.
131
+
For your convenience there are few config examples to achieve different serialization formats for an object `{ "a": { "b": 1 }, "c": [2, 3] }`:
127
132
128
-
Instead of writing any code by hand for fetching particular resources, we will let Swaggie do it for us.
Once you know what your backend expects, you can adjust the configuration file accordingly: (below are default values)
143
+
144
+
```json
145
+
{
146
+
"queryParamsSerialization": {
147
+
"arrayFormat": "repeat",
148
+
"allowDots": true
149
+
}
150
+
}
151
+
```
152
+
153
+
### Code Quality
129
154
130
155
> Please note that it's **recommended** to pipe Swaggie command to some prettifier like `prettier`, `biome` or `dprint` to make the generated code look not only nice, but also persistent.
131
156
> Because Swaggie relies on a templating engine, whitespaces are generally a mess, so they may change between versions.
132
157
133
-
### Suggested prettiers
158
+
**Suggested prettiers**
134
159
135
160
[prettier](https://prettier.io/) - the most popular one
136
161
@@ -151,7 +176,7 @@ You are not limited to any of these, but in our examples we will use Prettier. P
151
176
Let's run `swaggie` against PetStore API and see what will happen:
let url =`/pet/${encodeURIComponent(`${petId}`)}`;
176
203
177
204
returnaxios.request<Pet>({
178
205
url: url,
@@ -208,17 +235,75 @@ You might wonder how to set up server to fully utilize Swaggie's features. For t
208
235
209
236
Server is not necessary to use Swaggie. Swaggie cares only about the JSON/yaml file with the Open API spec, but for your development purpose you might want to have a server that can serve this file automatically from the actual endpoints.
210
237
211
-
## Notes
238
+
## Competitors
239
+
240
+
If you are familiar with the client-code generators for the Swagger / OpenAPI standards then you might wonder why `swaggie` is better than existing tools. I compiled a quick comparison with other tools below:
241
+
242
+
### Swaggie
243
+
244
+
- Fast and small 
If you are familiar with the client-code generators for the Swagger / OpenAPI standards then you might wonder why `swaggie` is better than existing tools. Currently the most popular alternative is an open-source `NSwag`.
0 commit comments