swagger-api/swagger-main/swagger-editor/docs/migration.md

Migrate from SwaggerEditor@4 to SwaggerEditor@next

Table of Contents

• Introduction
• Development
  • Start script with hot-reloading
  • Static build script
  • Local & remote definitions
  • Linting
  • Dependencies
  • Testing
• Design
  • Plugins
    • plugins available at release
    • plugins not yet migrated
  • Layout

Introduction

SwaggerEditor@next is a ground-up rewrite of SwaggerEditor@4. However, SwaggerEditor@4 is still fundamentally based on the SwaggerUI plugin system, and continues to be developed within the React ecosystem. For users without custom plugins or other forked customizations, SwaggerEditor@next is intended to be mostly drop-in compatible with the existing SwaggerEditor@4.

SwaggerEditor@4 introduces integration with ApiDOM and Microsoft's Monaco Editor. ApiDOM replaces the parser from SwaggerClient, as well as existing custom validation from SwaggerEditor@4. Monaco Editor replaces Ace Editor. Additional documentation on features and usage of ApiDOM and Monaco Editor can be found within their respective documention. Also available are the ApiDOM Playground and Monaco Editor Playground

This migration guide is intended to highlight setup changes and key customization features for SwaggerEditor@next.

Development

SwaggerEditor@next is using forked Create React App as it's building infrastructure. Therefore there are a few minor differences to develop SwaggerEditor@next

Start script with hot-reloading

new:

$ npm start

old:

$ npm run dev

Static build script

new:

$ npm run build:app
$ npm run build:app:serve

old:

$ npm start

Local & remote definitions

Only files inside public can be used from public/index.html. JS files must be put inside src.

new:

<SwaggerEditor url={url} />

old: In dev-helpers/index.html, add a url key like this:

const editor = SwaggerEditorBundle({
  dom_id: '#swagger-editor',
  url: "some-local-or-remote-path-to-definition.yaml" # define path here
  layout: 'StandaloneLayout',
  presets: [
    SwaggerEditorStandalonePreset
  ]
})

Linting

Automatic linting checks remain part of the commit process. SwaggerEditor@4 now generally follows the eslint recommendations from the AirBnb and React teams.

There is currently a known issue between compatibility of eslint-config-airbnb and eslint-config-react-app. The workaround is to set DISABLE_ESLINT_PLUGIN=false in the npm script.

Dependencies

SwaggerEditor@next is now based on swagger-ui-react instead of swagger-ui. In addition, unlike SwaggerEditor@4, SwaggerEditor@next does not have a dependency on SwaggerClient.

Testing

Unit tests are now covered by jest and @testing-library. Unit tests are now co-located next to their component. Component tests follow the @testing-library philosophy to avoid including implementation details, so that changes to implementation but not functionality doesn't break existing tests.

E2E Cypress tests remain in the test/cypress directory.

Design

Plugins

SwaggerEditor@next maintains its core as an extension of SwaggerUI's plugin system. SwaggerEditor@next exports itself as a fully realized set of plugins, each of which can be extended and wrapped as needed. This even includes the new Monaco Editor feature as a plugin!

Compared to SwaggerEditor@4, there is also no change to precedence with regards to the order of loading plugins.

SwaggerEditor@next provides a modals plugin for a unified modal system. The modals plugin is further extended via the dialogs plugin which provides a set of alert and confirm modal dialogs.

Any existing custom plugins for SwaggerEditor@4 that modified the behavior of, or directly interfaced with, the Ace Editor will likely need to be heavily refactored. Custom validation rules should be migrated to ApiDOM as needed.

plugins available at release

• dialogs
• dropzone
• editor-monaco
• editor-persistence
• editor-preview-asyncapi
• editor-preview-swagger-ui
• editor-read-only
• editor-spec-origin
• editor-textarea
• layout
• modals
• topbar

plugins not yet migrated

At the time of this writing there are two plugins from SwaggerEditor@4 that have not been migrated:

1. jump-to-path. Note: expect to leverage ApiDOM and editor-monaco plugin to replace AST and Ace Editor.
2. topbar-insert. Note: expect to leverage and wrap components of various existing plugins: topbar, editor-monaco, modals, and dialogs.

Layout

SwaggerEditor@next comes with a plugin for a "core" layout. The "core" layout provides plug points that are analogous to "panes" and/or "bars" in other IDEs. These plug points make it easier for developers to create plugins that customize their UX with as minimal changes to the "core" layout as possible.

The "core" layout includes contains EditorPane, EditorPreviewPane, and Topbar. These three components represent the basic UX wireframe for SwaggerEditor@next. In addition, the EditorPane is provided with four surrounding bars (top, bottom, left, right) that can each be customized with their own wrapped implementations.

Using itself as a reference design, SwaggerEditor@next provides implementation of two different EditorPane (editor-monaco and editor-textarea), and two different EditorPreviewPane (editor-preview-swagger-ui and editor-preview-asyncapi). The editor-monacoplugin also further extends the baseEditorPaneBarTopandEditorPaneBarBottom` with its own wrapped version of each.