Swaggie

此分支用于发版 swaggie-bate ,不要合并

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.

You can take a look at the Examples section down below.

Project is based and inspired by OpenApi Client.

Install

In your project

npm install swaggie --save-dev

Or globally to run CLI from anywhere

npm install swaggie -g

CLI

Usage: swaggie [options]

Options:

  -h, --help               output usage information
  -V, --version            output the version number
  -c, --config <path>      The path to the configuration JSON file. You can do all the set up there instead of parameters in the CLI
  -s, --src <url|path>     The url or path to the Open API spec file
  -t, --template <string>  Template used forgenerating API client. Default: "axios"
  -o, --out <path>         The path to the file where the API would be generated
  -b, --baseUrl <string>   Base URL that will be used as a default value in the clients. Default: ""
  --preferAny              Use "any" type instead of "unknown". Default: false
  --servicePrefix <string>  Prefix for service names. Useful when you have multiple APIs and you want to avoid name collisions. Default: ''
  --queryModels <bool>     Generate models for query string instead list of parameters. Default: false

Sample CLI usage using Swagger's Pet Store:

1swaggie -s https://petstore.swagger.io/v2/swagger.json -o ./client/petstore/

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:

1swaggie -s $URL -o ./client/petstore.ts && prettier ./client/petstore.ts --write`

And this can be easily automated (in the npm scripts for example)

Configuration File

Instead of providing all required flags from the command line you can alternatively create a new JSON file where you can fill up all settings.

Sample configuration looks like this:

1{
2  "$schema": "https://raw.githubusercontent.com/yhnavein/swaggie/master/schema.json",
3  "out": "./src/client/petstore.ts",
4  "src": "https://petstore.swagger.io/v2/swagger.json",
5  "template": "axios",
6  "baseUrl": "/api",
7  "preferAny": true,
8  "servicePrefix": "",
9  "queryModels": true,
10  "dateFormat": "Date" // "string" | "Date"
11}

Templates

The following templates are bundled with Swaggie:

axios     Default template. Recommended for React / Vue / similar frameworks. Uses axios
swr-axios Template that embraces SRW for GET requests and as a fallback uses axios.
fetch     Template similar to axios, but with fetch API instead. Recommended for React / Vue / similar frameworks
ng1       Template for Angular 1 (this is for the old one)
ng2       Template for Angular 2+ (uses HttpClient, InjectionTokens, etc)

If you want to use your own template, you can use the path to your template for the -t parameter:

swaggie -s https://petstore.swagger.io/v2/swagger.json -o ./client/petstore --template ./my-swaggie-template/

Code

1const swaggie = require('swaggie');
2swaggie
3  .genCode({
4    src: 'http://petstore.swagger.io/v2/swagger.json',
5    out: './api/petstore.ts',
6  })
7  .then(complete, error);
8
9function complete(spec) {
10  console.info('Service generation complete');
11}
12
13function error(e) {
14  console.error(e.toString());
15}

Usage – Integrating into your project

Let's assume that you have a PetStore API as your REST API and you are developing a client app written in TypeScript that will consume this API.

Instead of writing any code by hand for fetching particular resources, we will let Swaggie do it for us.

Please note that it's recommended to pipe Swaggie command to some prettifier like prettier or dprint to make the generated code look not only nice, but also persistent. Because Swaggie relies on a templating engine, whitespaces are generally a mess, so they may change between versions.

Suggested prettiers

prettier - the most popular one

1prettier ./FILE_PATH.ts --write

dprint - the superfast one

1dprint fmt ./FILE_PATH.ts

You are not limited to any of these, but in our examples we will use Prettier. Please remember that these tools needs to be installed first and they need a config file in your project.

Example

Let's run swaggie against PetStore API and see what will happen:

1swaggie -s https://petstore.swagger.io/v2/swagger.json -o ./api/petstore.ts && prettier ./api/petstore.ts --write

1// ./api/petstore.ts
2
3import Axios, { AxiosPromise } from 'axios';
4const axios = Axios.create({
5  baseURL: '/api',
6});
7
8/** [...] **/
9
10export const petClient = {
11  /**
12   * @param petId
13   * @return Success
14   */
15  getPetById(petId: number): AxiosPromise<Pet> {
16    let url = '/pet/{petId}';
17
18    url = url.replace('{petId}', encodeURIComponent('' + petId));
19
20    return axios.request<Pet>({
21      url: url,
22      method: 'GET',
23    });
24  },
25
26  // ... and other methods ...
27};

When we have that we can write some domain code and use this auto-generated classes:

1// app.ts
2
3import { petClient } from './api/petClient';
4
5petClient.getPetById(123).then((pet) => console.log('Pet: ', pet));

If Petstore owners decide to remove method we use, then after running swaggie again it will no longer be present in the petClient class. This will result in the build error, which is very much appreciated at this stage.

Without this approach, the error would be spotted by our end-user and he/she would not appreciate it at all!

Server config

You might wonder how to set up server to fully utilize Swaggie's features. For that I've added a samples/ folder with sample configurations.

ASP.NET Core + Nswag

ASP.NET Core + Swashbuckle

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.

Notes

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.

Quick comparison table:

swaggie	NSwag
- Written in node.js	- Written in .NET
- Fast	- Slow
-	-
- Easy to contribute to	- Contributing hard
- Lightweight	- Complicated templates
- Only features generating API clients for TS/JS	- Many more features (but mostly for .NET apps)

change

• 2023-03-17

  • md5Name 生成规则修改，去除使用 tag name

• 2023-01-11

  • add md5Name in operations