DEV Community

Cover image for New Swagger-UI embedding Cloud TypeScript Editor with RPC SDK
Jeongho Nam
Jeongho Nam

Posted on • Edited on

New Swagger-UI embedding Cloud TypeScript Editor with RPC SDK

#openapi #swagger #opensource #typescript

@nestia/editor

Nestia Editor Example

Swagger-UI embedding Cloud TypeScript Editor and RPC SDK.

@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!

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 />
Enter fullscreen mode Exit fullscreen mode

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

Unzipped

💾 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>
Enter fullscreen mode Exit fullscreen mode

<iframe> Embedding 

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

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.

Swagger File Uploader

Nestia Editor Example

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.

Top comments (0)