OpenAPI GUI

Inspiration

I wanted to try making a tool to generate Firebase code from Swagger, which allows users to create servers and clients with a single click based on an OpenAPI Specification. However, just reading the documentation on how to create the schema took me 6-8 hours, so I instead built a UI to speed up generating the OpenAPI Specification documents.

What it does

As the name suggests, it's a GUI to generate an OpenAPI Specification that can be used in tools like Swagger to automatically generate API clients, servers, and documentation.

In particular, there are a few key points of added value that OpenAPI GUI has over writing it by hand:

1. Embedded documentation - Not sure what a field means or why it is important? The documentation on that field is write there as you're filling it in.
2. Data validation - For objects that may have mutual exclusive fields, or require a specific type of resource like an email, a url, or something selected from a small list, OpenAPI GUI has you covered so you don't need to think about any of it. Every specification it generates is guaranteed to be accurate, which is especially important for linked objects that reference other places of the document.
3. Quick Triage for Hackathons - Don't have time to read the entire documentation? Just pay attention to the fields marked as required, and breeze though getting a basic OpenAPI Specification out as soon as possible. OpenAPI GUI still has all the features you could want though to turn a hackathon project into a real project though too!
4. Advanced Text Fields - Don't know Markdown or a programming language well enough you can write it blindly in a textbox? OpenAPI GUI provides rendered previews of all of those fields for you're viewing pleasure.
5. Easy conversion between OpenAPI 3.0.3 and OpenAPI 3.1.0 - OpenAPI 3.1.0 is the future of the platform as it is now compatible with JSON Schema. That being said, most tooling doesn't support OpenAPI 3.1.0 yet. Therefore, you can use OpenAPI GUI to generate you're new specification, then use the safe conversion feature to turn it back into OpenAPI 3.0.3 to connect with other tools!
6. Helpful Hints for New Hackers - Along with what you can find if you do spend the time scouring the OpenAPI Documentation, OpenAPI GUI has extra hints geared to helping beginners be successful at hackathons!

With all these features, OpenAPI GUI is perfect for any new (or existing) hacker who wants to jumpstart their project using OpenAPI.

How we built it

I build the entire project using React, Typescript, and Material UI. This allows it to run responsively in any browser from any device anywhere.

Challenges we ran into

It took forever to generate the OpenAPI data types into TypeScript definitions, and then with 8 hours left to go in the Hackathon we found out that while our plan was to target OpenAPI 3.1.0 (as this is the latest release), most tooling still only supports OpenAPI 3.0.3, so I had to go back and make a safe conversion engine between the two that ensures the maximum amount of data gets converted, any errors get specifically flagged for review, and if you roll back forward any information removed from the specification comes right back for you.

Accomplishments that we're proud of

• Completed OpenAPI GUI for the first 3 stages of an OpenAPI Specification: Configuration, Information, and Server
• Completed an Import and Export serialization system to convert from the model OpenAPI GUI uses on the back end to text the user can take to other tools like Swagger to generate clients, servers, and documentation from the OpenAPI specification
• Completed a Conversion Engine to safely transition between OpenAPI 3.1.0 and OpenAPI 3.0.3

What we learned

I learned a ton about OpenAPI and JSON Schema, which is really cool because both of those are things I've wanted to learn anyways, and will be using at work before the summer is over most likely.

What's next for OpenAPI GUI

Going forward, the goal is to finish expanding OpenAPI GUI out to the entire OpenAPI Specification, and add autowiring for things like the API paths so that when you define a data type, it automatically creates the API path specification for you and you just need to approve it.

Built With

• react
• typescript