Skip to Content
📖 Guide DocumentsSwagger DocumentCloud Swagger Editor

Nestia Editor

Example Case

Swagger UI, but with a real TypeScript editor.

@nestia/editor pairs the OpenAPI document browser you’re used to with a StackBlitz -powered TypeScript playground that has the generated SDK pre-installed. Click an endpoint → it opens in the editor with autocomplete on the request DTO, the response type, and every helper. Press run; the call goes through, the response comes back, and you can step through the TypeScript code that called it.

Two things flip on automatically:

  • Mockup simulator — the SDK answers without a backend, so reviewers can drive your API even when the server is offline.
  • Auto e2e tests — every endpoint ships with a randomized test you can run with one click.

Below are some live editors you can open right now to see the workflow.

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
Last updated on
AI Chatbot DevelopmentDocumentation Strategy