Stop using swagger-ui only, go with TypeScript SDK in browser
Tags: openapi, swagger, opensource, typescript
Published: 2024-03-30 17:57:29

## Outlline
[![Uploader](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yg1u2nu2n7rv7li9w4vs.png)](https://nestia.io/docs/editor)

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`](https://nestia.io/docs/editor). 

Just upload `swagger.json` to the [`@nestia/editor`](https://nestia.io/docs/editor), then it will open a new window that is commposed with both `swagger-ui` and online TypeScript editor (of [`StackBlitz`](https://stackblitz.com/)) 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)](https://stackblitz.com/edit/yyf3nl?file=README.md,test%2Fstart.ts&startScript=swagger&startScript=hello)
    - [Shopping Mall](https://stackblitz.com/edit/eue3bo?file=README.md,test%2Fstart.ts&startScript=swagger&startScript=hello)
    - [Clickhouse](https://stackblitz.com/edit/p5y9u3?file=README.md,test%2Fstart.ts&startScript=swagger&startScript=hello)
    - [Fireblocks](https://stackblitz.com/edit/jvdf9f?file=README.md,test%2Fstart.ts&startScript=swagger&startScript=hello)
    - [Iamport](https://stackblitz.com/edit/ldlfqp?file=README.md,test%2Fstart.ts&startScript=swagger&startScript=hello)
    - [Toss Payments](https://stackblitz.com/edit/hdtksu?file=README.md,test%2Fstart.ts&startScript=swagger&startScript=hello)

[![Example case](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/utxn81dmcasbx6fj03ic.png)](https://stackblitz.com/edit/eue3bo?file=README.md,test%2Fstart.ts&startScript=swagger&startScript=hello)

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`](https://nestia.io/docs/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`](https://nestia.io/docs/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`](https://nestia.io/docs/editor) will even automate the mockup server composition.




## Traditional way - `swagger-ui`
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/v4ev4mid7xba0lb5as9f.png)

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`](https://nestia.io/docs/editor) website, upload your `swagger.json` file. Then [`@nestia/editor`](https://nestia.io/docs/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`](https://nestia.io/docs/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`](https://nestia.io/docs/editor) provides [Mockup Simulator](https://nestia.io/docs/sdk/simulator). With the simulator, you can start the frontend (or client) development even when the backend API is not ready yet. 

Furthermore, [`@nestia/editor`](https://nestia.io/docs/editor) supports automatic [e2e (end-to-end) test functions' generation](https://nestia.io/docs/sdk/e2e), 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](https://trpc.io), but much advanced
  - Mockup Simulator
    - embedded backend simulator in the SDK
    - similar with [msw.js](https://mswjs.io), but fully automated

![Example case (gif)](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/v6b9s2zpt7g80e0uu8vf.gif)




## Demonstration
Here are the example projects of [`@nestia/editor`](https://nestia.io/docs/editor).

Traveling those example projects, you may understand how to utilize the [`@nestia/editor`](https://nestia.io/docs/editor). Let's start the type safe API interaction development with [`@nestia/editor`](https://nestia.io/docs/editor)!

  - [BBS (Bullet-in Board System)](https://stackblitz.com/edit/yyf3nl?file=README.md,test%2Fstart.ts&startScript=swagger&startScript=hello)
  - [Shopping Mall](https://stackblitz.com/edit/eue3bo?file=README.md,test%2Fstart.ts&startScript=swagger&startScript=hello)
  - [Clickhouse](https://stackblitz.com/edit/p5y9u3?file=README.md,test%2Fstart.ts&startScript=swagger&startScript=hello)
  - [Fireblocks](https://stackblitz.com/edit/jvdf9f?file=README.md,test%2Fstart.ts&startScript=swagger&startScript=hello)
  - [Iamport](https://stackblitz.com/edit/ldlfqp?file=README.md,test%2Fstart.ts&startScript=swagger&startScript=hello)
  - [Toss Payments](https://stackblitz.com/edit/hdtksu?file=README.md,test%2Fstart.ts&startScript=swagger&startScript=hello)




## How to use in local
```bash
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](https://nestia.io/docs/migrate)

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`](https://nestia.io/docs/editor).
For reference, if your backend application utilizes [`nestia`](https://github.com/samchon/nestia) (NestJS), you don't need to build the SDK (Software Development Kit) library by converting from the Swagger Documents. The [`nestia`](https://github.com/samchon/nestia) will automatically generate the much advanced SDK library, just by analyzing your backend application's source code.

> ![Nestia Logo](https://nestia.io/logo.png)
>
> [Nestia](https://github.com/samchon/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