https://github.com/OAIE/oaie-sketch

OpenAPI Visual Editor
https://github.com/OAIE/oaie-sketch

browser oas3 openapi openapi3 swagger visualeditor yaml

Last synced: 9 days ago
JSON representation

OpenAPI Visual Editor

• Host: GitHub
• URL: https://github.com/OAIE/oaie-sketch
• Owner: OAIE
• License: mit
• Created: 2020-03-31T09:03:18.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2021-06-06T22:42:06.000Z (over 3 years ago)
• Last Synced: 2024-07-17T12:37:37.321Z (4 months ago)
• Topics: browser, oas3, openapi, openapi3, swagger, visualeditor, yaml
• Language: HTML
• Size: 554 KB
• Stars: 63
• Watchers: 6
• Forks: 9
• Open Issues: 3
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# 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

![oaie-sketch-2.png](oaie-sketch-2.png)

## 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

        

    ...

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.