swagger-api/swagger-editor

Swagger Editor

⏰️ Looking for the next generation version of Swagger Editor?

SwaggerEditor is now released under two major release channels:

1. SwaggerEditor@4 - released from master branch and deployed at https://editor.swagger.io/
2. SwaggerEditor@5 - released from next branch and deployed at https://editor-next.swagger.io/

Only SwaggerEditor@5 supports OpenAPI 3.1.0. SwaggerEditor@4 will not receive OpenAPI 3.1.0 support and is considered legacy at this point. The plan is to continually migrate fully to SwaggerEditor@5 and deprecate the SwaggerEditor@4 in the future.

---

🕰️ Looking for the older version of Swagger Editor? Refer to the 2.x or 3.x branches.

---

Swagger Editor lets you edit OpenAPI API definitions (OpenAPI 2.0 and OpenAPI 3.0.3) in JSON or YAML format inside your browser and to preview documentations in real time. Valid OpenAPI definitions can then be generated and used with the full Swagger tooling (code generation, documentation, etc).

As a brand-new version, written from the ground up, there are some known issues and unimplemented features. Check out the Known Issues section for more details.

This repository publishes to two different NPM modules:

• swagger-editor is a traditional npm module intended for use in single-page applications that are capable of resolving dependencies (via Webpack, Browserify, etc).
• swagger-editor-dist is a dependency-free module that includes everything you need to serve Swagger Editor in a server-side project, or a web project that can't resolve npm module dependencies.

If you're building a single-page application, using swagger-editor is strongly recommended, since swagger-editor-dist is significantly larger.

Helpful scripts

Any of the scripts below can be run by typing npm run <script name> in the project's root directory.

Developing

Script name	Description
dev	Spawn a hot-reloading dev server on port 3200.
deps-check	Generate a size and licensing report on Swagger Editors's dependencies.
lint	Report ESLint style errors and warnings.
lint-errors	Report ESLint style errors, without warnings.
lint-fix	Attempt to fix style errors automatically.
watch	Rebuild the core files in /dist when the source code changes. Useful for npm link.

Building

Script name	Description
build	Build a new set of JS and CSS assets, and output them to /dist.
build:bundle	Build swagger-editor-bundle.js only (commonJS).
build:core	Build swagger-editor.(js|css) only (commonJS).
build:standalone	Build swagger-editor-standalone-preset.js only (commonJS).
build:stylesheets	Build swagger-editor.css only.
build:es:bundle	Build swagger-editor-es-bundle.js only (es2015).
build:es:bundle:core	Build swagger-editor-es-bundle-core.js only (es2015).

Testing

Script name	Description
test	Run unit tests in Node, run Cypress end-to-end tests, and run ESLint in errors-only mode.
test:unit-mocha	Run Mocha-based unit tests in Node.
test:unit-jest	Run Jest-based unit tests in Node.
e2e	Run end-to-end browser tests with Cypress.
lint	Run ESLint test
test:artifact	Run list of bundle artifact tests in Jest
test:artifact:umd:bundle	Run unit test that confirms swagger-editor-bundle exports as a Function
test:artifact:es:bundle	Run unit test that confirms swagger-editor-es-bundle exports as a Function
test:artifact:es:bundle:core	Run unit test that confirms swagger-editor-es-bundle-core exports as a Function

Running locally

Prerequisites

• git, any version
• Node.js >=20.3.0 and npm >=9.6.7 are the minimum required versions that this repo runs on, but we always recommend using the latest version of Node.js.

 $ npm i --legacy-peer-deps

If you have Node.js and npm installed, you can run npm start to spin up a static server.

Otherwise, you can open index.html directly from your filesystem in your browser.

If you'd like to make code changes to Swagger Editor, you can start up a Webpack hot-reloading dev server via npm run dev.

Browser support

Swagger Editor works in the latest versions of Chrome, Safari, Firefox, and Edge.

Known Issues

To help with the migration, here are the currently known issues with 3.X. This list will update regularly, and will not include features that were not implemented in previous versions.

• Everything listed in Swagger UI's Known Issues.
• The integration with the codegen is still missing.

Docker

Running the image from DockerHub

There is a docker image published in DockerHub.

To use this, run the following:

docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor

This will run Swagger Editor (in detached mode) on port 80 on your machine, so you can open it by navigating to http://localhost in your browser.

• You can provide a URL pointing to an API definition (may not be available if some security policies such as CSP or CORS are enforced):

docker run -d -p 80:8080 -e URL="https://petstore3.swagger.io/api/v3/openapi.json" swaggerapi/swagger-editor

• You can provide your own json or yaml definition file from your local host:

docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json swaggerapi/swagger-editor

Note: When both URL and SWAGGER_FILE environment variables are set, URL has priority and SWAGGER_FILE is ignored.

• You can specify a different base url via BASE_URL variable for accessing the application - for example if you want the application to be available at http://localhost/swagger-editor/:

docker run -d -p 80:8080 -e BASE_URL=/swagger-editor swaggerapi/swagger-editor

• You can specify a different port via PORT variable for accessing the application, default is 8080.

docker run -d -p 80:80 -e PORT=80 swaggerapi/swagger-editor

You can also customize the different endpoints used by the Swagger Editor with the following environment variables. For instance, this can be useful if you have your own Swagger generator server:

Environment variable	Default value
URL_SWAGGER2_GENERATOR	https://generator.swagger.io/api/swagger.json
URL_OAS3_GENERATOR	https://generator3.swagger.io/openapi.json
URL_SWAGGER2_CONVERTER	https://converter.swagger.io/api/convert

If you want to run the Swagger Editor locally without the Codegen features (Generate Server and Generate Client) you can set the above environment variables to null (URL_SWAGGER2_CONVERTER=null).

Building and running an image locally

To build and run a docker image with the code checked out on your machine, run the following from the root directory of the project:

# Install npm packages (if needed)
npm install

# Build the app
npm run build

# Build an image
docker build -t swagger-editor .

# Run the container
docker run -d -p 80:8080 swagger-editor

You can then view the app by navigating to http://localhost in your browser.

Documentation

• Importing your OpenAPI document

• Contributing

Using older version of React

Important

By older versions we specifically refer to React >=17 <18.

By default swagger-editor@4 npm package comes with latest version of React@18. It's possible to use swagger-editor@4 npm package with older version of React.

Let's say my application integrates with swagger-editor@4 npm package and uses [email protected].

npm

In order to inform swagger-editor@4 npm package that I require it to use my React version, I need to use npm overrides.

{
  "dependencies": {
    "react": "=17.0.2",
    "react-dom": "=17.0.2"
  },
  "overrides": {
    "swagger-editor": {
      "react": "$react",
      "react": "$react-dom",
      "react-redux": "^8"
    }
  }
}

Note

The React and ReactDOM override are defined as a reference to the dependency. Since react-redux@9 only supports React >= 18, we need to use react-redux@8.

yarn

In order to inform swagger-editor@4 npm package that I require it to use my specific React version, I need to use yarn resolutions.

{
  "dependencies": {
    "react": "17.0.2",
    "react-dom": "17.0.2"
  },
  "resolutions": {
    "swagger-editor/react": "17.0.2",
    "swagger-editor/react-dom": "17.0.2",
    "swagger-editor/react-redux": "^8"
  }
}

Note

The React and ReactDOM resolution cannot be defined as a reference to the dependency. Unfortunately yarn does not support aliasing like $react or $react-dom as npm does. You'll need to specify the exact versions.

Security contact

Please disclose any security-related issues or vulnerabilities by emailing [email protected], instead of using the public issue tracker.

swagger-editor's Issues

Explore parsing YAML syntax

We need to get access to AST of YAML in order to able to modify the YAML programmatically. Explore our options.

Add codegen support

The killer demo is using the consolidated spec for codegen. It works like this.

There is an online codegen that lives here. It has a swagger description available here:

http://generator.wordnik.com

There are some bugs in the input model right now so the POST methods are not accurate. A proper usage is like such:

generate a java client:

EDIT: this is now on the wordnik domain

curl -X POST http://generator.wordnik.com/online/api/gen/client/java -H "Content-Type:application/json" -d @client.json -o java-client.zip

generate a objc client:

curl -X POST http://generator.wordnik.com/online/api/gen/client/objc -H "Content-Type:application/json" -d @client.json -o objc-client.zip

generate a jaxrs server:

curl -X POST http://generator.wordnik.com/online/api/gen/server/jaxrs -H "Content-Type:application/json" -d @server.json -o jaxrs-server.zip

client.json:

https://gist.github.com/mohsen1/ec3afcadef5e88a8cb50

Clicking on `#!` links in preview will navigate the preview panel to destination of the link

Updating the resourcePath doesn't change the child paths

This may be an issue of redundancy in the Swagger spec, but when I edit the resourcePath, I expect the child paths to update as well. Should the editor do this? Should the spec change?

Download JSON button

Using HTML5 File API make a file bulb and make it downloadable via a button.

Render swagger-ui pane from the YAML/JSON edit pane

Scroll into-view operation that is being edited currently

When I'm working on the summary of a method, I can't see it unless I expand and navigate to the detail view in the html. Ideally, the html knows where you are in the YAML and updates it automatically.

Example:

Remove initial animation

Persist on text editor's content via localStorage

It's great to be able to write YAML with live preview, but we need a way for people to save out their work (to file, local storage, git repo, whatever).

Add a new fav icon

Add delay for refreshing right-hand pane

Right now, when you start typing, the swagger-ui blanks out and tries to redraw. This can be jerky.

Instead, try leaving the swagger-ui in place until there hasn't been a keystroke for 500ms. Then draw the update.

This should solve the "jerkiness" and may enable us to remove the "live update" button.

Move project into swagger org

…assuming we can set one up, otherwise possibly Wordnik org.

• Move to new org (do issues move, too?)
• Add licensing notice
• Update the readme with info and how to participate

structural issue in consolidated format

If you look at existing consolidated format, the apiDeclarations key is at the same level as apis. In the default YAML, it's at the top level.

See here for what is expected:

https://gist.github.com/fehguy/e3e20da90179b1027480#file-gistfile1-yml-L33

The fix is easy:

line 56, main.js should be:

if(json && Array.isArray(json.model.apiDeclarations)){
$scope.apiDeclarations = json.model.apiDeclarations.map(buildapiDeclarationDocs);
}

Include assets for YAML syntax

Includes the default YAML and syntax guide pane.

Make a checkbox on header to disable auto render of docs

Put a checkbox on header for disabling auto rendering of docs.

Checkbox label should say "Auto-generate docs"
Initial state should be checked
By unchecking it auto generation of docs will be stopped and docs panel go dim
By checking it, docs get generated automatically and preview panel will un-dim

The 2 in "oauth2" is syntax-highlighted in a funny way.

Controls to expand/collapse YAML and HTML in sync

Consider adding controls that collapse the YAML down to the "method" and to also collapse the html pane down to the collapsed view. This is like a toggle of detailed vs simple.

Example:

Remove try-it functionality

No need to try it when the API is being designed and doesn't exist yet! In the short term, remove the try-it button and hide the auth config.

Support fenced blocks of multi-line descriptions, including markdown and/or html

Longer descriptions will eventually be necessary. The right way to handle this may be by fencing with ``` and then processing any markdown and/or html. This is out of scope for May.

Can't run locally

Any ideas why I'd get this message when running locally?

fehguy:phonics tony$ grunt serve

/Users/tony/dev/projects/fehguy/phonics/node_modules/grunt/node_modules/findup-sync/lib/findup-sync.js:33
    }).flatten().uniq().value();
       ^
TypeError: Object Gruntfile.js has no method 'flatten'
    at Object.module.exports [as findup] (/Users/tony/dev/projects/fehguy/phonics/node_modules/grunt/node_modules/findup-sync/lib/findup-sync.js:33:8)
    at Task.task.init (/Users/tony/dev/projects/fehguy/phonics/node_modules/grunt/lib/grunt/task.js:427:16)
    at Object.grunt.tasks (/Users/tony/dev/projects/fehguy/phonics/node_modules/grunt/lib/grunt.js:117:8)
    at Object.module.exports [as cli] (/Users/tony/dev/projects/fehguy/phonics/node_modules/grunt/lib/grunt/cli.js:38:9)
    at Object.<anonymous> (/usr/local/lib/node_modules/grunt-cli/bin/grunt:43:20)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Function.Module.runMain (module.js:497:10)

I have the following runtimes:

fehguy:phonics tony$ node --version
v0.10.21
fehguy:phonics tony$ grunt --version
grunt-cli v0.1.11
grunt v0.4.4

Code will be collapsed down to just show content related to location of preview panel

When navigating in preview panel, we should collapse the code panel to just show the content related to what's being shown in preview panel.

Refactor the YAML syntax

For example, editing the "resourcePath" doesn't update the child APIs' paths. Also, the "path" could be a top-level element rather than a child of "apis".

Marsh and Tony will work this out.

Implement the revised YAML syntax and consolidated json

In addition to the single, unified YAML file (whereas JSON is # of resources plus the root doc) and in re-usable YAML definitions, we'll want to consider any YAML-specific names. See: https://docs.google.com/a/apigee.com/document/d/1hrovNL4VQl0sUa5eLnFuoNcYVxu86LvS1z6wXJOkTOg/edit#

Action to download a client sdk

Generated from Tony's service (details to be provided)

Design error pane

When the YAML syntax is incorrect we hide documents and show an error pane. Please design the error pane with some icons and fonts. You can find the html file at invalid-docs.html.

Guidance for users unfamiliar with the YAML format

There will be many people who do not know the syntax for Swagger-YAML. We can help them with approaches like a syntax list on the right-hand pane, autocomplete, and/or buttons to "add a resource" or "add a method" or "add a query parameter", etc.

Make panel splitter movable so user can resize panels

Live updates to swagger-ui on YAML editor

This is probably already in the works, but right now live edit only works with JSON edits, not YAML.

Move JSON out of editor and over to html pane

YAML has reusable bits that get rendered into JSON. The problem is that is lossy—there isn't an easy way to preserve the relationship of the JSON back to the original definition. This has potential to complicate the 2-way editing process (as does the multiple file aspect of JSON).

Instead, let's move JSON out of the edit pane and over to the swagger-ui pane. Then you can see the docs or switch to the JSON view.

Additional panels beyond YAML and Swagger-ui panes

Consider an approach more like jsbin where you can toggle multiple panels. This might include:

• YAML
• JSON
• Template (for generating docs)
• HTML (or docs)

As you edit in YAML, the JSON would update, and vice versa (except for the reusable bit, need to think about that)

URL will get updated on navigation

SwaggerUI has it's own navigation router system. Manage to integrate that routing system into our app.

For example #!/pet/deletePet should be translated to /#/pet/deletePet

Add Swagger icon and nav behaviors to topnav

Work with @MMux to allow for whatever should happen when you hover or click the swagger icon.

Add instructions for building and running locally

The readme should include something like:

Node must already be installed on your local machine.

npm install
bower install
grunt serve

Make it hard for people to lose their work

Not necessary for the POC, but at some point we need to warn folks about losing their work when they try to do things like close their tab or reload their page.

YAML Linting

This story refers to item number 3 below…

There are at least three ways we can help guide users:

1. Auto-complete. Minimum is the total syntax, best is contextual to the structure's location
2. Contextual help to offer syntax guidance (could be as simple as an expandable pane or dialog)
3. Validation of the Swagger-YAML (linting). This is more than just creating valid YAML—it includes checking for required elements, etc.
4. Buttons such as "add a resource" or "add a method" or "add a query parameter", etc.

The guiding question is, "How do we make authoring the swagger-yaml easy for people who do not yet know the synax?"

Resolve the conflict between distributed resources

Swagger-JSON defines the root description with api-doc, such as:
petstore.swagger.wordnik.com/api/api-docs

This tells you the individual resources families that you get a description for each.

YAML should have a unified view of all the description in one file. How to deal with this?

Deal with consolidated swagger-json

Guidance from @fehguy:
Updated library which takes consolidated JSON:
https://github.com/wordnik/swagger-js/blob/develop/lib/swagger.js

and corresponding swagger-ui branch:

https://github.com/wordnik/swagger-ui/tree/develop/dist

You can see an example in this test script:

https://github.com/wordnik/swagger-js/blob/develop/src/specs/petstore_1_2_spec.js#L441

Note there is an array of “apiDeclarations” which literally map to the swagger json for each root resource. So if you take this:

http://petstore.swagger.wordnik.com/api/api-docs

add a key “apiDeclarations” with array value containing each of these:

http://petstore.swagger.wordnik.com/api/api-docs/pet

http://petstore.swagger.wordnik.com/api/api-docs/store

http://petstore.swagger.wordnik.com/api/api-docs/user

You’d have the “consolidated JSON”.

When using this with swagger-ui, you simply initialize it as follows:

window.swaggerUi = new SwaggerUi({url: “URL”, obj: THE_SWAGGER_CONSOLIDATED_OBJECT, ….

Wire up new ace theme

Here's a new theme based on atom-dark, but it needs some @mohsen1 magic to work with 'grunt ship'.

https://github.com/apigee/swagger-editor/blob/master/app/bower_components/ace-builds/src-min-noconflict/theme-atom_dark.js

Add filters for custom YAML specification

We like to have more specs on top of JSON specific specs. For example renamed keys in YAML. Those keys would get translated during YAML-to-JSON conversion

@earth2marsh please write specific key names we need to translate to generate JSON

Buttons for common tasks

Beginners unfamiliar with the swagger-yaml syntax may benefit from buttons to add path, method, params, and even re-usable params.

Enable saving and loading of one's work

If you do work, you need a way to save and restore it. This could be done in localstorage, or it could be a github repo/gist integration, or it could be the filesystem.

YAML merge issue

seems like the YAML 2 JSON process is not processing merges or anchors

Add Help button to navbar for user guidance

A small button that can provide and context / help to users

Tweak styling to align with visual design mocks

Work with @MMux to resolve the header height, colors, etc.

Compatibiity with Swagger-styling

Today the header is orange, but that isn't necessarily harmonious with the Swagger styles. Petstore is a good example. @fehguy may have guidance here…

Note that Swagger 2 will present a chance to revisit the Swagger style.

When clicking "New", right pane should show "invalid or empty..." message

Better resource path YAML syntax

Instead of:

• path: "/pet/{petId}"

… it would be nicer to use:
/pet/{petId}

Autocompletion of swagger-yaml

related to #25, is the idea of autocompletion. At its simplest, this might be tab-completion of a key name. Even better would be if it could also understand the YAML schema, so that appropriate values could be decided between. ACE has both "snippets" and "autocomplete, see: https://github.com/ajaxorg/ace/wiki/How-to-enable-Autocomplete-in-the-Ace-editor

Snippets example using XSLT: https://github.com/ajaxorg/ace/blob/a4a30b6665da5f5ef9c3bd23d7bac01374bae450/lib/ace/snippets/xslt.snippets

Consider snippets for adding a full now path or method element. Best of all would be if it could pull context from the working doc so that if I've defined a reusable YAML param, then I could choose from the list of those names.

Import an existing Swagger description into YAML

Point the YAML editor to a Swagger endpoint and then generate the YAML as the starting point.

Allow definition of re-usable YAML bits

Swagger's YAML generator does support re-usable YAML bits that can then be referred to later. We should support this and allow creation of those reusable snippets.