Getting Started

Swagger Editor is the official open source editor for designing and documenting APIs using the OpenAPI Specification (OAS). It gives you a split-pane view with a YAML/JSON editor on the left and live-rendered interactive documentation on the right, with real-time validation highlighting any schema errors. Available as an open web service in Eyevinn Open Source Cloud, Swagger Editor is ready to use instantly with no build steps or local installation.

Prerequisites

Step 1: Create a Swagger Editor instance

Navigate to the Swagger Editor service in the Eyevinn OSC web console. Click Create swagger-editor and fill in:

Field Description Example
Name Short alphanumeric name for your instance myeditor
ApiDefinitionUrl (Optional) URL of an existing OpenAPI YAML or JSON file to load on startup https://petstore.swagger.io/v2/swagger.json

Click Create and wait for the status indicator to turn green and show running.

Step 2: Open the editor

Click the instance URL to open Swagger Editor in your browser. No login is required.

The editor loads with a sample Petstore API definition (or your own definition if you supplied ApiDefinitionUrl). Edit the YAML or JSON in the left panel — the right panel updates in real time to show the rendered API documentation and any validation errors.

Step 3: Design your API

Swagger Editor validates your OpenAPI document as you type and highlights errors inline. A few things you can do:

  • Import an existing definition: Click File > Import URL or File > Import File to load an API spec.
  • Export: Click File > Save as YAML or File > Convert and save as JSON to download your spec.
  • Try it out: The rendered documentation panel includes a Try it out button for each endpoint. Enter a server URL at the top of the spec and execute live requests directly from the browser.
  • Generate client/server stubs: Click Generate Client or Generate Server to download a code skeleton for your chosen language (Node.js, Python, Java, Go, etc.).

Loading a remote API definition at startup

If you supply ApiDefinitionUrl when creating the instance, Swagger Editor fetches and loads that definition automatically each time the page is opened. This is useful for keeping a shared team editor always pointing at your API's canonical spec file in a git repository or an artifact store.

# Create an editor that loads the Petstore spec on startup
osc create swagger-api-swagger-editor teameditor \
  -o ApiDefinitionUrl="https://petstore.swagger.io/v2/swagger.json"

CLI usage

osc create swagger-api-swagger-editor myeditor

Resources