134 lines
5.7 KiB
Markdown
134 lines
5.7 KiB
Markdown
## Swagger Editor Legacy (v3/v4) Migration Summary
|
|
|
|
### Topbar Features
|
|
[x] Import from URL
|
|
[x] Import from File
|
|
[x] Save As Json
|
|
[x] Save As Yaml
|
|
[x] Convert from Json to Yaml, then download
|
|
[x] Convert from Yaml to Json, then download
|
|
[x] Convert from Json to Yaml, in editor only
|
|
[x] Clear Editor (moved from File Menu to Edit Menu)
|
|
[x] Convert from OAS2 to OAS3
|
|
[x] Generate Servers list - OAS2
|
|
[x] Generate Servers list - OAS3.0
|
|
[x] Generate Clients list - OAS2
|
|
[x] Generate Clients list - OAS3.0
|
|
[x] Display/Hide menu items based on combination of json/yaml, oas2/oas3
|
|
[x] NEW: consistent use of styled Modal components throughout (react-modal)
|
|
[x] NEW: Load default OAS2/OAS3/OAS3.1/AsyncApi2 definition; w/keyboard shortcuts
|
|
[x] Removed: topbar-insert (plugin); no replacement planned
|
|
|
|
|
|
### Editor Features
|
|
[x] NEW: Monaco Editor
|
|
[x] NEW: validation from apidom-ls library
|
|
[x] Removed: Ace Editor
|
|
[x] Removed: internal validation from swagger-editor v3/v4
|
|
[x] Drag-n-drop local file to editor (react-dropzone)
|
|
[x] Persist definition on browser refresh/reload (localStorage)
|
|
[x] Display validation pane results
|
|
|
|
|
|
### Visual UI Features
|
|
[x] SwaggerUI v4; React 17
|
|
|
|
|
|
### Implementation Changes
|
|
[x] React Hooks support, e.g. menu item display toggle, modal system
|
|
[x] Behavioral testing of components, e.g. not the implementation details
|
|
[x] Simplify and reorganize `presets`, `layouts`, and `plugins`
|
|
[x] Extract menu action methods from Components to Actions
|
|
[x] Extract menu logic helpers to Actions
|
|
[x] Extract shared menu logic helpers to `utils/editor-converter`
|
|
[x] Replace `fetch` with `axios` http helpers to `utils/topbar-http`
|
|
[x] deprecate plugins with direct implementation: Convert to OAS3, Import File
|
|
[x] Removed: unnecessary state where possible
|
|
[x] Removed: window.alert and window.confirm popups
|
|
[x] Removed: swagger-client library dependency
|
|
[x] Tests: testing-library + jest (unit), cypress (e2e)
|
|
|
|
|
|
### Possible additional/expanded docs/contributing topics
|
|
[x] Separation of actions from components. tldr: easier to test, possibly more re-usable
|
|
[x] React Hooks. tldr: modern practices
|
|
[x] testing-library. tldr: focus on user behaviors, more durable/maintainable tests
|
|
[x] reorganizing the presets. e.g. what happened to `standalone` and other plugins? The new recommended structure. tldr: multi-spec, multi-layouts
|
|
|
|
|
|
### List of migrated legacy methods
|
|
Note: likely to remove this section from final doc
|
|
|
|
Extract menu action methods from React to Actions
|
|
[x] importFromURL
|
|
[x] saveAsYaml
|
|
[x] saveAsJson
|
|
[x] convertToYaml
|
|
[x] downloadGeneratedFile
|
|
[x] importFile
|
|
[x] onDocumentLoad prop - removed. handled now in actions. Theoretically, we could expose as a user-overwritable function. Maybe SH needed it?
|
|
[x] updateEditorContent prop - will be removed, and handled in actions.
|
|
[x] clearEditor
|
|
|
|
Deprecate methods from React
|
|
[x] saveAsText
|
|
[x] handleResponse
|
|
|
|
Extract menu logic helpers to Actions
|
|
[x] getGeneratorUrl
|
|
[x] instantiateGeneratorClient
|
|
[x] shouldReInstantiateGeneratorClient (new)
|
|
|
|
Extract menu logic helpers to utils-converter
|
|
[x] hasParserErrors
|
|
[x] getFileName
|
|
[x] getDefinitionLanguage
|
|
[x] getDefinitionVersion
|
|
|
|
Create (axios) http method to utils-http
|
|
[x] getDefinitionFromUrl
|
|
[x] getGenerator2Definition
|
|
[x] postPerformOasConversion
|
|
|
|
Remove unnecessary state:
|
|
[x] swaggerClient
|
|
[x] definitionVersion
|
|
|
|
Remove use of alert and confirm via new modal system
|
|
[x] alert
|
|
[x] confirm
|
|
|
|
|
|
### Additional notes (remove from final doc)
|
|
[x] swagger-ui redux state
|
|
[x] connect monaco state to swagger-ui redux state
|
|
[x] connect actions with monaco state, e.g. updateEditorContent
|
|
[x] init oas spec via swagger-ui
|
|
[x] connect & sync generic-editor updates to swagger-ui
|
|
[x] init oas spec via import File (finish action) - Json
|
|
[x] init oas spec via import File (finish action) - Yaml
|
|
[x] init oas spec via import Url (finish action)
|
|
[x] CSS/Less/Saas styling
|
|
[x] remove use of mock data in topbarActions. (mock fixtures not removed yet)
|
|
[x] try react-modal lib instead of creating internal version
|
|
[x] modify generic-editor plugin to have a default editor placeholder (instead of calling GenericEditorContainer directly)
|
|
[x] add disposables array, and ability to dispose()
|
|
[x] make generator servers/clients toggleable; enable oas3.1/others when supported
|
|
[x] File Menu dropdown - add json/yaml detection to display appropriate link
|
|
[x] Edit menu dropdown - render convert to OAS3 only if currently 'isSwagger2`
|
|
[x] Edit menu dropdown - render convert to Yaml only if currently 'json'
|
|
[x] onboard - default definition should be in YAML format
|
|
|
|
### Resolved Issues (remove from final doc)
|
|
|
|
[x] ~~fix exploding styling/rendering when using in-browser (ctrl+f) find text within monaco; monaco's find+replace feature~~ USING P2M/M2P FIXES THIS ISSUE
|
|
[x] ~~warning: overlapping semantic tokens~~ THIS IS APIDOM-LS ISSUE
|
|
[x] fix editor configuration/onChange to always word-wrap.
|
|
[x] remove "dev mode" case when editor content is undefined
|
|
[x] remove mock data/fixtures/configuration from `actions.js`
|
|
[x] in codeActionUi, sometimes recieve an Uncaught promise TypeError: d.dispose is not a funtion
|
|
[x] asyncapi support: anywhere we should be detecting async api (or any other supported spec); e.g. clearEditor
|
|
[x] handle apidom parser throw, when unable to detect langugage. e.g. empty string, or oas2
|
|
[x] load default (oas3). note the topbar generate server/client exists. -> clear all. user may type random string. note that the topbar generate server/client did NOT disappear
|
|
[x] load default -> import OAS2. note the topbar generate server/client exists. -> clear all. user may type random string. note that the topbar generate server/client did NOT disappear
|