dev-resources.site

for different kinds of informations.

New Swagger-UI embedding Cloud TypeScript Editor with RPC SDK

Published at

10/29/2024

`@nestia/editor`

Swagger-UI embedding Cloud TypeScript Editor and RPC SDK.

Live Preview
- Shopping Mall Example: https://nestia.io/editor/?url=shopping.json
- Swagger File Uploader: https://nestia.io/editor
Guide Documents: https://nestia.io/docs/editor
Github Repository: https://github.com/samchon/nestia

@nestia/editor is a combination of Swagger-UI and web-based TypeScript editor (of StackBlitz) embedding RPC (Remote Procedure Call) styled SDK (Software Development Kit) library generated from an OpenAPI Document.

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

Also, @nestia/editor provides Mockup Simulator of the backend API functions. With the mockup simulator, you can start the frontend (or client) development even when the backend API funtions have not been implemented yet. Furthermore, @nestia/editor supports automatic E2E (end-to-end) test functions' generation, so that you can easily validate the backend API functionns with the automatically generated test codes.

Here are the some example projects generated by @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!

Concepts
- SDK: collection of typed fetch functions with DTO structures
- Mockup Simulator: embedded backend simulator in the SDK
Demo Editors

React Library

import { NestiaEditorIframe } from "@nestia/editor";
import { SwaggerV2, OpenApiV3, OpenApiV3_1 } from "@samchon/openapi";

const document: SwaggerV2 | OpenApiV3 | OpenApiV3_1;

<NestiaEditorIframe swagger={document}
                    package="your-package-name" 
                    e2e={true} 
                    simulate={true} />
<NestiaEditorUploader />

Install @nestia/editor and import one of below components.

If you've prepared the Swagger Document to serve, you can directly launch the cloud editor by using the NestiaEditorIframe component. Otherwise you want to provide a "Swagger File Uploader" for dynamic purpose, utilize the NestiaEditorUploader component instead.

NestiaEditorIframe: directly launch the cloud editor by given document
NestiaEditorUploader: upload the swagger.json file and launch the cloud editor

Static Hosting

💾 https://nestia.io/downloads/editor.zip

Unzip and place your swagger.json file into the extracted directory.

Just download unzip the above editor.zip file, nd place your swagger.json (or swagger.yaml) file into the extracted directory. When you open the unzipped index.html in your browser, you can see the @nestia/editor is serving the "TypeScript Swagger Editor" application with your swagger.json (or swagger.yaml) file.

Also, if you want to specify the package name, or activate the Mockup Simulator, open the index.html file of unzipped and edit some variables like below. Guiding the users th fill these package, simulate and e2e query parameters like http://localhost/?simulate=true&e2e=true can be an alternative way.

By the way, if you do not place the swagger.json (or swagger.yaml) file into the directory, the @nestia/editor will just show you the "Swagger File Uploader" (NestiaEditorUploader) instead.

<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta
      name="viewport"
      content="width=device-width, height=device-height, initial-scale=1, minimum-scale=1.0, maximum-scale=3.0s"
    />
    <title>Nestia Editor</title>
    <script type="module"  src="./assets/index-DwHERS4Q.js"></script>
  </head>
  <body style="width: 100%; height: 100%; margin: 0px; overflow: hidden;">
    <div id="root" style="width: 100%; height: 100%"></div>
    <script>
      window.package = "@ORGANIZATION/PROJECT";
      window.simulate = false; 
      window.e2e = false;
    </script>
  </body>
</html>

`<iframe>` Embedding

<iframe url="https://nestia.io/editor/?url={URL_ADDRESS}&package={NAME}&simulate=true&e2e=true"></iframe>

You also can embed the @nestia/editor with static URL address.

When embedding the @nestia/editor application through the <iframe> tag, fill the url query parameter with the URL address of your swagger.json (or swagger.yaml) file. Also, the simulate and e2e query parameters are optional, but recommended to be filled with true for the best experience. As you know, they activate the Mockup Simulator and automatic e2e test functions' generation.

By the way, if you do not fill the url query parameter, the @nestia/editor will just show you the "Swagger File Uploader" (NestiaEditorUploader) instead.

If you wanna see the example cases of the <iframe> embedding, let's see the below list again.

BBS (Bullet-in Board System): https://nestia.io/editor/?url=bbs.json
Shopping Mall: https://nestia.io/editor/?url=shopping.json
Clickhouse: https://nestia.io/editor/?url=clickhouse.json
Fireblocks: https://nestia.io/editor/?url=fireblocks.json
Uber: https://nestia.io/editor/?url=uber.json
OpenAI: https://nestia.io/editor/?url=openai.json

Swagger File Uploader

If you visit https://nestia.io/editor without any URL query parameters, the Swagger File Uploader be loaded.

Just upload your Swagger (OpenAPI document) file, and click the "generate editor" button. Then, TypeScript SDK library would be generated from your OpenAPI document, and it would be combined with the traditional Swagger-UI in the Cloud TypeScript Editor.

openapi Article's

30 articles in total