Service: Swagger Editor - EyevinnOSC/community GitHub Wiki

Swagger Editor

Swagger Editor (serviceId swagger-api-swagger-editor, license Apache-2.0) is the open source editor for designing and documenting APIs with the OpenAPI Specification. It shows a YAML/JSON editor next to live-rendered interactive documentation, with real-time validation. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance.

What it can do

  • Edit OpenAPI definitions in JSON or YAML and preview documentation in real time.
  • Validate the document as you type and highlight schema errors inline.
  • Import an existing definition (File, Import URL or Import File) and export it as YAML or JSON.
  • Try endpoints from the rendered documentation, using the server URL given in the spec.
  • Generate client or server stubs for languages such as Node.js, Python, Java and Go.

Creating an instance

Swagger Editor has no dependencies. Call create-service-instance with serviceId: "swagger-api-swagger-editor":

{
  "name": "myeditor",
  "ApiDefinitionUrl": "https://petstore.swagger.io/v2/swagger.json"
}

ApiDefinitionUrl is optional; leave it out to get the default sample Petstore definition. Wait with wait-for-service-ready or get-instance-status, then use describe-service-instance to get the instance URL. No login is required.

Equivalent OSC CLI usage:

osc create swagger-api-swagger-editor myeditor
# or with a definition loaded on startup
osc create swagger-api-swagger-editor teameditor \
  -o ApiDefinitionUrl="https://petstore.swagger.io/v2/swagger.json"

Options

Option Required Type Meaning
name Yes string Name of the instance. Letters, digits and underscore (^\w+$); OSC limits names to 20 characters.
ApiDefinitionUrl No string URL of an existing OpenAPI YAML or JSON file to load when the editor opens, for example https://petstore.swagger.io/v2/swagger.json. Without it the editor loads a sample Petstore definition.

Using the instance

Open the instance URL. Edit the definition in the left panel; the right panel updates to show the rendered documentation and validation errors.

If ApiDefinitionUrl is set, the editor fetches and loads that definition each time the page is opened. This is useful for a shared team editor pointing at your API's canonical spec file in a git repository or an artifact store.

Resources