Generate typescript from openapi  
Tags: typescript, restful, openapi, service
Published: 2021-11-01 02:06:32

## Openapi doc for typescript integration.

When we use typescript to connect restful api, there are many toos to generate the target service code. How to choose, here are some simple comparisons to reference.

## example source [https://github.com/superwf/ts-gear-example](https://github.com/superwf/ts-gear-example)

## 🆚 Compare


### Here are 5 tools && 5 openapi doc => 5x5 results

#### Swagger pet store openapi v2

Fixture source: [https://petstore.swagger.io/v2/swagger.json](https://petstore.swagger.io/v2/swagger.json)

- ✅ `ts-gear`

  - command: `yarn tsg -p tsGearPetV2`

  - result position: `src/service/tsGearPetV2/`

  Actually, run `yarn tsg` without `-p` will generate all service code configured in `src/tsg.config.ts`

- ✅ `pont`

  - command: `yarn pont`

  - result position: `src/service/pont/petV2/`

  Actually, run `yarn pont` will generate all service code configured in `pont-config.json`, in other fixtures case it does not need run again.

  😢 The request functions generated by pont do **NOT**connect  request parameters type nor response data type.

- ✅ `openapi-generator`

  - command: `yarn openapiGeneratorPetV2`

  - result position: `src/service/openapiGeneratorPetV2/`

- ✅ `swagger-codegen`

  - command: `yarn swaggerCodegenPetV2`

  - result position: `src/service/swaggerCodegenPetV2/`

- ✅ `oazapfts`

  - command: `yarn oazapftsPetV2`

  - result position: `src/service/oazapftsPetV2.ts`

✅ All tools generate result successfully.

#### Swagger pet store openapi v3

Fixture source: [https://petstore3.swagger.io/api/v3/openapi.json](https://petstore3.swagger.io/api/v3/openapi.json)

- ✅ `ts-gear`

  - command: `yarn tsg -p tsGearPetV3`

  - result position: `src/service/tsGearPetV3/`

- ✅❌ `pont`

  - command: `yarn pont`

  - result position: `src/service/pont/petV3/`

  😢 Run OK, but **No definition data type** generated.

- ✅ `openapi-generator`

  - command: `yarn openapiGeneratorPetV3`

  - result position: `src/service/openapiGeneratorPetV3/`

- ✅ `swagger-codegen`

  - command: `yarn swaggerCodegenPetV3`

  - result position: `src/service/swaggerCodegenPetV3/`

- ✅ `oazapfts`

  - command: `yarn oazapftsPetV3`

  - result position: `src/service/oazapftsPetV3.ts`

✅ All tools generate result successfully.

#### Bad defined example 1

Fixture source: [https://raw.githubusercontent.com/superwf/ts-gear-example/master/fixture/badDefined1.json](https://raw.githubusercontent.com/superwf/ts-gear-example/master/fixture/badDefined1.json)

- ✅ `ts-gear`

  - command: `yarn tsg -p tsGearBadDefined1`

  - result position: `src/service/tsGearBadDefined1/`

- ✅❌ `pont`

  - ✅ command: `yarn pont`

  - ❌result position: `src/service/pont/badDefined1/`

  😢 Run OK, but **No meaningful** code generated.

- ✅❌ `openapi-generator`

  - command: `yarn openapiGeneratorBadDefined1`

  - ❌ result: `error Command failed with exit code 1`

  the command tell me use `--skip-validate-spec` to skip validate, so try again with it.

  - command: `yarn openapiGeneratorBadDefined1 -- --skip-validate-spec`

  - result position: `src/service/openapiGeneratorBadDefined1/`

  😢 Run OK, but many data type definition missing.

- ✅❌ `swagger-codegen`

  - command: `yarn swaggerCodegenBadDefined1`

  - ❌ result position: `src/service/swaggerCodegenBadDefined1/`

  😢 Run OK, but many data type definition missing.

- ❌ `oazapfts`

  - command: `yarn oazapftsBadDefined1`

  - result: `UnhandledPromiseRejectionWarning: MissingPointerError: Token "ReplyVO«PageVO«FieldDefListVO»»" does not exist`

### Bad defined example 2

Fixture source: [https://raw.githubusercontent.com/superwf/ts-gear-example/master/fixture/badDefined2.json](https://raw.githubusercontent.com/superwf/ts-gear-example/master/fixture/badDefined2.json)

- ✅ `ts-gear`

  - command: `yarn tsg -p tsGearBadDefined2`

  - result position: `src/service/tsGearBadDefined2/`

- ✅❌ `pont`

  - command: `yarn pont`

  - result position: `src/service/pont/badDefined2/`

  😢 **No meaningful** code generated.

- ✅❌ `openapi-generator`

  - command: `yarn openapiGeneratorBadDefined2`

  - result: `error Command failed with exit code 1`

  the command tell me use `--skip-validate-spec` to skip validate, so try again with it.

  - command: `yarn openapiGeneratorBadDefined2 -- --skip-validate-spec`

  - result position: `src/service/openapiGeneratorBadDefined2/`

  😢 Run OK, but many data type definition missing.

- ✅❌ `swagger-codegen`

  - command: `yarn swaggerCodegenBadDefined2`

  - result position: `src/service/swaggerCodegenBadDefined2/`

  😢 Many data type definition missing and type name error.

- ❌ `oazapfts`

  - command: `yarn oazapftsBadDefined2`

  - result: `UnhandledPromiseRejectionWarning: MissingPointerError: Token "ListVO" does not exist`

### Bad defined example 3

Fixture source: [https://raw.githubusercontent.com/superwf/ts-gear-example/master/fixture/badDefined3.json](https://raw.githubusercontent.com/superwf/ts-gear-example/master/fixture/badDefined3.json)

- ✅ `ts-gear`

  - command: `yarn tsg -p tsGearBadDefined3`

  - result position: `src/service/tsGearBadDefined3/`

- ✅ `pont`

  - command: `yarn pont`

  - result position: `src/service/pont/badDefined3/`

- ✅❌ `openapi-generator`

  - ✅ command: `yarn openapiGeneratorBadDefined3`

  - ❌ result: `src/service/openapiGeneratorBadDefined3/`

  😢 Run OK, but result code has syntax error, can not be used directly.

- ✅❌ `swagger-codegen`

  - command: `yarn swaggerCodegenBadDefined3`

  - result position: `src/service/swaggerCodegenBadDefined3/`

  😢 Run OK, but result code has syntax error, can not be used directly.

- ❌ `oazapfts`

  - command: `yarn oazapftsBadDefined3`

  - result: `UnhandledPromiseRejectionWarning: MissingPointerError: Token "Map" does not exist`

### Summary

| tool |  bad doc compatible🌟 | comment output | Generic type | independent request export | more language support | mock data | custom request logic | translate none english | filter api | openapi V2 & V3 |
| ---- | ---- | ----- | ----- | ---- | --- | --- | --- | --- | --- | --- |
| ts-gear | ✅ | ✅ | ✅<a href="#generic-type-👀">👀</a> | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
| pont | ✅❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ |
| openapi-generator | ❌ | ✅ | ✅<a href="#generic-type-👀">👀</a> | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ |
| swagger-codegen | ❌ | ✅ | ✅<a href="#generic-type-👀">👀</a> | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ |
| oazapfts | ❌ | ✅ | ✅<a href="#generic-type-👀">👀</a>| ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |

- `Openapi-generator` and `Swagger-codegen` are the most common industry general tools, they are powerfull for supportting many program languages and special env.

- Only `pont` and `ts-gear` use configuration file, all other tools just use cli arguments.

- `ts-gear` has proved its self the compatibility with bad defined openapi doc.

### Generic type 👀

Whether can generate generic type successfully, depends on the complement of openapi doc definition.