Generate typescript from openapi

superwf — Mon, 01 Nov 2021 02:06:32 +0000

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

🆚 Compare

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

Swagger pet store openapi v2

Fixture source: 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 NOTconnect 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

✅ 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

✅ 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

✅ 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

✅ 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	✅	✅	✅👀	✅	❌	✅	✅	✅	✅	✅
pont	✅❌	✅	❌	✅	✅	❌	✅	✅	❌	❌
openapi-generator	❌	✅	✅👀	❌	✅	❌	✅	❌	❌	✅
swagger-codegen	❌	✅	✅👀	❌	✅	❌	✅	❌	❌	✅
oazapfts	❌	✅	✅👀	✅	❌	❌	❌	❌	❌	✅

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.

DEV Community: superwf

Generate typescript from openapi

Openapi doc for typescript integration.

example source https://github.com/superwf/ts-gear-example

🆚 Compare

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

Swagger pet store openapi v2

Swagger pet store openapi v3

Bad defined example 1

Bad defined example 2

Bad defined example 3

Summary

Generic type 👀