oaie/oaie-sketch

OpenAPI Visual Editor

OAIE Sketch

OAIE Sketch is a browser-based editor for OAS3 spec documents. It offers a side-by-side YAML code editor and visual editor with a focus on tactile feedback, simplicity and performance. Its philosophy is "stay close to the code and visualize".

Online Demo: https://raw.githack.com/OAIE/oaie-sketch/master/sketch.html

Installation

Currently OAIE Sketch is only a few files plus CDN links. So your process to get it running is manual.

• clone repository
• open sketch.html in browser

Features

• shows each operation as graph node (path, operationId, summary, parameters)
• shows each schema as graph node (name, description, properties)
• shows each relation as graph arrow (array-relations as dotted)
• dragging for graph nodes
• mass-move to make space for new content (up/down arrows in operation)
• quick action buttons for adding properties and schemas
• clicking schemas or properties will scroll the document
• detects changes and colors sync buttons
• can add a "baked" viz into the document as a viewer storage
• uses viz as metadata (node position) storage
• sync graph into yaml, sync yaml into graph
• auto-save in localstorage of browser

Opinionated OAS3 YAML

Requests, Responses and sub-objects should be their own schema definitions. Note that this is best practice anyway if you ever want to generate classes from your spec.

components:
  schemas:
    CapabilitiesRequest:
      required:
        - spec
      properties:
        spec:
          $ref: '#/components/schemas/Spec'
    CapabilitiesResponse:
      properties:
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/Capability'
    Capability:
      properties:
        method:
          type: string
        skuPattern:
          type: string
    Spec:
      description: OAIE.noInArrows
      properties:
        id:
          type: string
        schedules:
          type: array
          items:
            $ref: '#/components/schemas/Schedule'
    Schedule:
      properties:
        method:
          type: string
        expression:
          type: string

VIZ

Beginning documents like this will add a viz (visualisation) into the header (this will show up as a graphic in swagger):

openapi: "3.0.0"
info:
  version: "0.0.1"
  title: My Service
  description: |
    My introductory information
    <!--OAIE.viz--><!--/OAIE.viz-->
...

Sketch persists graph node positions to the browser's localStorage, but when a viz is present, it will store and load graph node positions to and from this viz (inside the <!--OAIE.viz--> tag).

Caveats

• Currently only tested on Chrome.
• OAIE Sketch has an opinion about correct document structure: each schema should be declared as a named schema.
• local storage is used as persistence. this means that currently it is only feasible to edit one spec at a time (much like the Swagger online editor).
• OAIE Sketch is in a very early stage, please backup your documents frequently outside of it!
• Sync: when both are yellow, first click "<- update inline viz", then "update from editor ->"

TODO

• documentation
• find contributors
• marketing
• see Projects tab for planned features

Contributing

• We want to maintain a focus on the code.
• We want to facilitate writing better specs.
• We want to make writing specs easier and give an easier learning curve.
• We want to be as lightweight as possible (currently needs Vue, JS-YAML, jQuery, jQuery UI - help on removing jQuery appreciated!).
• We want to keep the dependency to libraries as low as possible.

oaie-sketch's Issues

Feature Request: Viz Layout

I really love this tool - it is the first one I jumped to. One thing I'd like to know is if you have plans to add some kind of auto-layout option to it. As you can see, my schema is pretty ridiculous, and it takes forever to drag everything around.

VueJs compile error

<div id="app" :class="{ editorWide: editorWide }">
		<div id="specEditor" v-if="!settings">
			<div v-for="(settingsKey, settingsName) in allSettings" class="settings" @click="selectSettings(settingsKey)">{{Â&nbsp;settingsName }}</div>
			<div class="settings new" @click="newSettings()">+ Create a new spec</div>
		</div>
		<div id="specEditor" v-if="settings">
			<div class="editor">
				<div class="measureHelper">Text</div>
				<textarea wrap="off" v-model="settings.spec" @change="save(); editorChanged = true;" spellcheck="false"></textarea>
			</div>
			<span class="editorWideToggle" @click="editorWide = !editorWide">{{Â&nbsp;editorWide ? '⧀' : '⧁' }}</span>
		</div>
		<div id="outputViewer" v-if="settings">
			<div class="menu">
				<button @click="load" :class="{ changed: editorChanged }">→ update from editor</button>
				<button @click="updateInlineViz" :class="{ changed: positionsChanged }">← update inline
					viz</button>
				<!--<button @click='dump'>&equiv; dump to console</button>-->
				<button @click="addSchema">⊕ schema</button>
				<div v-if="spec &amp;&amp; spec.info" class="title">{{ spec.info.title }} <span class="version">{{ spec.info.version }}</span></div>
			</div>
			<div id="output">
				<a v-for="(connection, c) in connections" v-bind:class="[&quot;arrow&quot;, connection.type]" v-bind:source="connection.source" v-bind:target="connection.target" v-bind:id="&quot;connection&quot; + c"></a>
				<div v-bind:class="[&quot;operation&quot;, operation._method]" v-bind:id="operation._key" v-bind:oaie-key="operation._key" v-bind:style="{ left: getPositionLeft(operation._key), top: getPositionTop(operation._key) }" v-for="operation in operations" v-draggable="">
					<div class="path">
						<b>{{Â&nbsp;operation._method }}</b>
						<span @click="selectPath(&quot;paths:/&quot; + encodeURIComponent(operation._path) + &quot;:/&quot; + operation._method + &quot;:&quot;)">{{ operation._path }}</span>
					</div>
					<div class="buttonRow">
						<button class="mini" @click="moveAllY(operation, -50)">↑</button>
						<button class="mini" @click="moveAllY(operation, 50)">↓</button>
					</div>
					<div class="summary"><b>{{ operation.operationId }}</b> {{ operation.summary }}</div>
					<ul>
						<li v-for="parameter in operation.parameters" v-bind:class="{ required: parameter.required }">
							<button>-</button>
							<span @click="selectPath(&quot;paths:/&quot; + encodeURIComponent(operation._path) + &quot;:/&quot; + operation._method + &quot;:/parameters:/- name: &quot; + parameter.name, parameter.name)">
								{{Â&nbsp;parameter.name }} ({{Â&nbsp;parameter.schema.type }})
							</span>
						</li>
						<li><button>+</button></li>
					</ul>
				</div>
				<div class="schema" v-if="spec &amp;&amp; spec.components" v-for="(schema, schemaName) in spec.components.schemas" v-bind:id="&quot;schema.&quot; + schemaName" v-bind:oaie-key="&quot;schema.&quot; + schemaName" v-bind:style="{ left: getPositionLeft(&quot;schema.&quot; + schemaName), top: getPositionTop(&quot;schema.&quot; + schemaName) }" v-draggable="">
					<h1 @click="selectPath(&quot;components:/schemas:/&quot; + schemaName + &quot;:&quot;)">{{ schemaName }}</h1>
					<div class="description">{{ schema.description }}</div>
					<ul>
						<li v-for="(property, propertyName) in schema.properties">
							<button>-</button>
							<span @click="selectPath(&quot;components:/schemas:/&quot; + schemaName + &quot;:/properties:/&quot; + propertyName + &quot;:&quot;)">
								{{Â&nbsp;propertyName }}
								({{Â&nbsp;property.type ? property.type : property.$ref ? property.$ref.replace('#/components/schemas/', '→') : '' }})
						</span></li>
						
						<li><button @click="addSchemaProperty(schema, schemaName)">+</button></li>
					</ul>
				</div>
			</div>
		</div>
	</div>

- invalid expression: missing ) after argument list in

    _s( settingsName)

  Raw expression: {{ settingsName }}

- invalid expression: missing ) after argument list in

    _s( editorWide ? '⧀' : '⧁')

  Raw expression: {{ editorWide ? '⧀' : '⧁' }}

- invalid expression: missing ) after argument list in

    _s( operation._method)

  Raw expression: {{ operation._method }}

- invalid expression: missing ) after argument list in

    "\n\t\t\t\t\t\t\t\t"+_s( parameter.name)+" ("+_s( parameter.schema.type)+")\n\t\t\t\t\t\t\t"

  Raw expression: {{ parameter.name }} ({{ parameter.schema.type }})

- invalid expression: missing ) after argument list in

    "\n\t\t\t\t\t\t\t\t"+_s( propertyName)+"\n\t\t\t\t\t\t\t\t("+_s( property.type ? property.type : property.$ref ? property.$ref.replace('#/components/schemas/', '→') : '')+")\n\t\t\t\t\t\t"

  Raw expression: {{ propertyName }}
								({{ property.type ? property.type : property.$ref ? property.$ref.replace('#/components/schemas/', '→') : '' }})



(found in <Root>)

This happens when I load the page. Using tag 0.2.1