Stop using swagger-ui only, go with TypeScript SDK in browser

Outlline

https://nestia.io/docs/editor

If you're a frontend developer, stop using swagger-ui standalone.

Instead, go with TypeScript SDK (Software Development Kit) generated by @nestia/editor.

Just upload swagger.json to the @nestia/editor, then it will open a new window that is commposed with both swagger-ui and online TypeScript editor (of StackBlitz) with automatically generated SDK library.

• Features of SDK
  • collection of typed fetch functions
  • DTO structures written in TypeScript
  • Mockup simulator for testing
• Github Repository: https://github.com/samchon/nestia
• Demonstrations
  • BBS (Bullet-in Board System)
  • Shopping Mall
  • Clickhouse
  • Fireblocks
  • Iamport
  • Toss Payments

With the SDK, you don't need to be suffered from swagger documents reading, and hand-writing duplicated DTO definitions and fetch functions. @nestia/editor will do everything instead of you automatically, so that you can only focus on your business logic, and pure frontend application development.

For reference, the SDK library generated by @nestia/editor is even embedding the mockup simulator. Therefore, you no more need to hand-write the mockup server by yourself (e.g. msw). @nestia/editor will even automate the mockup server composition.

Traditional way - swagger-ui

If you're a frontend developer, and have received swagger documents from backend, you may open it on swagger-ui.

Reading a swagger documents from swagger-ui, you may implement interaction code with backend server using axios or fetch function. You also need to write DTO (Data Transfer Object) structures looking at JSON schema definitions. Some professional frontend developers even build a mocking backend server through msw for testing.

During above processes, you may take a mistake that mis-reading API specs, or mis-writing DTO structures. Also, mocking the backend server with msw, you can misunderstand the real backend server's API specs. As long as front-end developers are human, not robots, these are all common mistakes we see all around us.

By the way, such common mistakes sometimes cause serious problems in the real world. At least, such mistakes never be caught by compiler, but only by runtime. The more mistakes we make, the harder it is to catch and debug. Of course, even if there are no mistakes, redundant DTO or fetch function implementation and msw mocking code by hand is very laborious and cumbersome works.

• Hand-writings
  • fetch functions
  • DTO structures
  • msw mocking code
• Redundant and laborious works
• Mistakes are not caught in compile time

New era - Software Development Kit

By the way, if such processes can be fully automated, how it would be?

Visit @nestia/editor website, upload your swagger.json file. Then @nestia/editor will analyze the target swagger.json file, and write TypeScript codes instead of you. The automatically generated TypeScript codes will contain all of the following features, and I call it as SDK (Software Development Kit).

• Typed fetch functions
• DTO structures
• Mockup simulator for testing

With the cloud @nestia/editor, you can easily test the backend API with TypeScript code, and it is much convenient than the traditional way of using Swagger UI, due to type checking and auto-completion.

Also, @nestia/editor provides Mockup Simulator. With the simulator, you can start the frontend (or client) development even when the backend API is not ready yet.

Furthermore, @nestia/editor supports automatic e2e (end-to-end) test functions' generation, so that you can easily validate the API with the generated test code.

• SDK (Software Development Kit)
  • collection of typed fetch functions with DTO structures
  • similar with tRPC, but much advanced
• Mockup Simulator
  • embedded backend simulator in the SDK
  • similar with msw.js, but fully automated

Demonstration

Here are the example projects of @nestia/editor.

Traveling those example projects, you may understand how to utilize the @nestia/editor. Let's start the type safe API interaction development with @nestia/editor!

• BBS (Bullet-in Board System)
• Shopping Mall
• Clickhouse
• Fireblocks
• Iamport
• Toss Payments

How to use in local

npx @nestia/migrate
? Migration mode (Use arrow keys):
  > NestJS
    SDK
? Swagger file location: assets/input/clickhouse.json
? Output directory path: assets/output/clickhouse-sdk-manual
? Mokup Simulator: true
? E2E Test Functions: true

Related document: Nestia > Guide Documents > Migration from Swagger

Just run npx @nestia/migrate command in your terminal.

The @nestia/migrate program will ask you something, and then generate the SDK library in your local machine, what you've seen in the @nestia/editor.
For reference, if your backend application utilizes nestia (NestJS), you don't need to build the SDK (Software Development Kit) library by converting from the Swagger Documents. The nestia will automatically generate the much advanced SDK library, just by analyzing your backend application's source code.

Nestia is a set of helper libraries for NestJS, supporting below features:

• Only one line required, with pure TypeScript type
• Enhance performance 30x up
  • Runtime validator is 20,000x faster than class-validator
  • JSON serialization is 200x faster than class-transformer
• Software Development Kit
  • Collection of typed fetch functions with DTO structures
  • Mockup simulator is embedded

Comments

[Abiria]

Thank you for awesome projects and articles each time!