đź“– Guide DocumentsTypeScript Swagger Editor

Outline

Example Case

Swagger-UI with Cloud TypeScript Editor with embedded SDK.

@nestia/editor is a combination of Swagger-UI and web-based TypeScript editor (of StackBlitz) embedding SDK (Software Development Kit) library generated by @nestia/migrate 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 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 functions 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 functions 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!

Swagger file uploader
Placeholder image
orto select swagger.json/yaml file



Generate Editor

Put your swagger.json file, then @nestia/editor be opened.

Frontend Setup

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

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, and 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.

editor/index.html
<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.

Backend Setup

Editor Module

src/main.ts
import { NestiaEditorModule } from "@nestia/editor/lib/NestiaEditorModule";
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
 
import { AppModule } from './app.module';
 
const bootstrap = async (): Promise<void> => {
  const app = await NestFactory.create(AppModule);
  const config = new DocumentBuilder()
    .setTitle('Cats example')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .addTag('cats')
    .build();
  const documentFactory = () => SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, documentFactory)
 
  await NestiaEditorModule.setup({
    path: "editor",
    application: app,
    swagger: "/api-json",
    package: "your-package-name",
    simulate: true,
    e2e: true,
  });
  await app.listen(3000);
};
bootstrap().catch(console.error);

In the NestJS, you can serve the Nestia Editor by NestiaEditorModule.setup() function.

Note that, if you’ve configured the path parameter of the SwaggerModule.setup() function (of @nestjs/swagger) as api, its URL path of the composed Swagger Document is /api-json. Fill the /api-json URL path into the swagger parameter of the NestiaEditorModule.setup() function.

Also, don’t forget to configure the additional properties like package, simulate and e2e for the best experience. Even though these properties are optional, but recommended to be fully filled with the proper values.

  • package: Name of the SDK package generated in the editor
  • simulate: Whether to compose mockup simulator or not
  • e2e: Whether to compose e2e automated test functions or not
Migration from Swagger