The OpenAPI 3.0 GUI

March 30, 2018

I have been editing my OpenAPI definitions manually for some time now, as I just haven’t found a GUI editor that works well with my workflow. Swagger editor really isn’t a GUI solution, and while I enjoy services like Stoplight.io, APIMATIC, and others, I’m very picky about what I adopt within my world. One aspect of this is that I’ve been holding out for a solution that I can run 100% on Github using Github Pages. I’ve delusionally thought that someday I would craft a slick JavaScript solution that I could run using only Github Pages, but in reality I’ve never had the time to pull together. So, I just kept manually editing my OpenAPI definitions on the desktop using Atom, and publish to Github as I needed.

Well, now I can stop being so dumb, because my friend Mike Ralphson (@permittedsoc) has created my new favorite OpenAPI GUI, that is OpenAPI 3.0 compliant by default. As Mike defines it, “OpenAPI-GUI is a GUI for creating and editing OpenAPI version 3.0.x JSON/YAML definitions. In its current form it is most useful as a tool for starting off and editing simple OpenAPI definitions. Imported OpenAPI 2.0 definitions are automatically converted to v3.0.”

He provides a pretty simple way to get up and running with OpenAPI GUI because, “OpenAPI-GUI runs entirely client-side using a number of Javascript frameworks including Vue.JS, jQuery and Bulma for CSS. To get the app up and running just browse to the live version on GitHub pages, deploy a clone to GitHub pages, deploy to Heroku using the button below, or clone the repo and point a browser at index.html or host it yourself - couldn’t be simpler.” – “You only need to npm install the Node.js modules if you wish to use the openapi-gui embedded web server (i.e. not if you are running your own web-server), otherwise they are only there for PaaS deployments.”

Portable, Forkable API Design GUI The forkability of OpenAPI GUI is what attracts me to it. The client-side JavaScript approach makes it portable and forkable, allowing it to run wherever it is needed. The ability to quickly publish using Github Pages, or other static environment, makes it attractive. I’d like to work on a one click way for deploying locally, so I could make available to remote microservices teams to use locally to manage their OpenAPI definitions. I think it is important to have local, as well as cloud-based API design GUI locations, with more investment in the cloud-base solutions being more shared, possessing a team component, as well as a governance layer. However, I really like the thought of each OpenAPI having its own default editor, and you edit the definition within the repo it is located. I could see two editions of OpenAPI GUI, the isolated edition, and a more distributed team and definition approach. IDK, just thinking out loud.

Setting the OpenAPI 3.0 Stage The next thing I love about OpenAPI GUI is that it is all about OpenAPI 3.0, which I just haven’t had the time to fully migrate to. It has the automatic conversion of OpenAPI definitions, and gives you all the GUI elements you need to manage the robust features present in 3.0 of the OpenAPI specification. I’m itching to get ALL of my API definitions migrated from 2.0 to 3.0. The modular and reusable nature of OpenAPI 3.0, enabled by OpenAPI GUI is a formula for a rich API design experience. There are a lot of features built into the expand and collapse GUI, which I could see becoming pretty useful once you get the hang of working in there. Adding, duplicating, copying, and reusing your way to a powerful, API-first way of getting things done. I like.

Bringing In The Magic With Wizards Ok, now I’m gonna go all road map on you Mike. You know you don’t have to listen to everything I ask for, but cherry pick the things that make sense. I see what you are doing in the wizard section. I like it. I want a wizard marketplace. Go all Harry Potter and shit. Create a plugin framework and schema so we can all create OpenAPI driven wizards that do amazing things, and users can plugin and remove as they desire. Require each plug to be its own repo, which can be connected and disconnected easily via the wizards tab. I’d even consider opening up the ability to link to wizards from other locations in the editor, and via the navigation. Then we are talking about paid wizards. You know, of the API validation varietal. Free validations, and then more advanced paid validations. ($$)

Branding And Navigation Customization I would love to be able name, organize, and add my own buttons. ;-) Let’s add a page that allows for managing the navigation bars, and even the icons that show within the page. I know it would be a lot of work, but a great thing to have in the road map. You could easily turn on the ability to add logo, change color palette, and some other basics that allows companies to easily brand it, and make it their space. Don’t get me wrong. It looks great now. It is clean, simple, uncluttered. I’ve just seen enough re-skinned Swagger UI and editors to know that people are going to want to mod the hell out of their GUI API design tooling. Oh yeah, what about drag and drop–I’d like to reorder by paths. ;-) Ok, I’ll shut up now.

OpenAPI GUI In A Microservices World As I said before, I like the idea of one editor == one OpenAPI. Something that can be isolated within the repo of a service. Don’t make things too complicate and busy. In my API design editor I want to be able to focus on the task at hand. I don’t want to be distracted by other services. I’d like this GUI to be the self-container editor accessible via the Jekyll, Github Pages layer for each of my microservices. Imagine a slightly altered API design experience for each service. I could have the workspace configurable and personalized for exactly what I need to deliver a specific service. I would have a base API design editor for jumpstarting a new service, but I’d like to be able to make the OpenAPI GUI fit each service like a glove, even making the About tab a README for the service, rather than for the editor–making it a microservice dashboard landing page for each one of my services.

Making API Design a Shareable Team Sport Ok, contradicting my anti-social, microservices view of things. I want the OpenAPI GUI to be a shareable team environment. Where each team member possesses their own GUI, and the world comes to them. I want a shared catalog of OpenAPI definitions. I want to be able to discover widely, and checkout or subscribe to within my OpenAPI GUI. I want all the reusable components to have a sharing layer, allowing me to share my components, work with the shared components of other developers, and work from a central repository of components. I want a discovery layer across the users, environments, components, OpenAPI definitions, and wizards. I want to be able to load my API design editor with all of the things I need to deliver consistent API design at scale. I want to be able to reuse the healthiest patterns in use across teams, and possibly lead by helping define, and refine what reusable resources are available for development, staging, and production environments.

Github, Gitlab, or BitBucket As A Backend For The OpenAPI GUI I want to run on Github, Gitlab, or BitBucket environments, as a static site–no backend. Everything backend should be an API, and added as part of the wizard plugin (aka magic) environment. I want the OpenAPI, components, and any other artifacts to live as JSON or YAML within a Github, Gitlab, or BitBucket repository. If it is an isolated deployment, everything is self-contained within a single repository. If it is a distributed deployment, then you can subscribe to shared environments, catalogs, components, and wizards via many organizations and repositories. This is the first modification I’m going to do to my version, instead of the save button saving to the vue.js store, I’m going to have it write to Github using the Github API. I’m going to add a Github OAuth icon, which will give me a token, and then just read / write to the underlying Github repository. I’m going to begin with an isolated version, but then expand to search, discovery, read and write to many different Github repositories across the organizations I operate across.

Annotation And Discussion Throughout While OpenAPI GUI is a full featured, and potentially busy environment, I’d like to be able to annotate, share, and discuss within the API design environment. I’d like to be able to create Github issues at the path level, and establish conversations about the design of an API. I’d like to be able to discuss paths, schema, tags, and security elements as individual threads. Providing a conversational layer within the GUI, but one that spans many different Github repositories, organizations, and users. Adding to the coupling with the underlying repository. Baking a conversational layer into the GUI, but also into the API design process in a way that provides a history of the design lifecycle of any particular service. Continuing to make API design a team sport, and allowing teams to work together, rather than in isolation.

API Governance Across Distributed OpenAPI GUIs With everything stored on Github, Gitlab, Bitbucket, and shareable across teams using organizations and repositories, I can envision some pretty interesting API governance possibilities. I can envision a distributed API catalog coming into focus. Indexing and aggregating all services, their definitions, and conversations aggregated across teams. You can see the seeds for this under the wizard tab with validation, visualization, and other extensions. I can see there being an API design governance framework present, where all API definitions have to meet certain number of validations before they can move forward. I can envision a whole suite of free and premium governance services present in a distributed OpenAPI GUI environment. With an underlying Github, BitBucket, and Gitlab base, and the OpenAPI GUI environment, you have the makings for some pretty sweet API governance possibilities.

Lot’s Of Potential With OpenAPI GUI I’ll pause there. I have a lot of other ideas for the API design editor. I’ve been thinking about this stuff for a long time. I’m stoked to adopt what you’ve built Mike. It’s got a lot of potential, and a nice clean start. I’ll begin to put to use immediately across my API Evangelist, API Stack, and other API consulting work. With several different deployments, I will have a lot more feedback. It’s an interesting leap forward in the API design tooling conversation, building on what is already going on with API service providers, and some of the other API design tooling like Apicurio, and publishing the API design conversation forward. I’m looking forward to baking OpenAPI GUI into operations a little more–it is lightweight, open source, and extensible enough to get me pretty excited about the possibilities.

Read more...

Previous Article
My API Stack Profiling Process
My API Stack Profiling Process

I am escalating conversations I’m having with folks regarding how I profile and understand APIs as part of...

Next Article
Obtaining A Scalable API Definition Driven API Design Workflow On Github Complete With API Governance
Obtaining A Scalable API Definition Driven API Design Workflow On Github Complete With API Governance

There is a lot of talk of an API design first way of doing things when it comes to delivering microservice...