OpenAPI Initiative, OpenAPI v3.1 Support, Oh(penAPI) My!

If you’re a longtime follower of ReadMe history, you’ll know that we’re no stranger to the OpenAPI Specification (OAS). Since our earliest days as a company, we’ve been:

• Writing blog posts about OAS ✍️ Our most viewed blog post is a short walkthrough of the differences between Swagger 2.x and OpenAPI 3.x!
• Supporting OAS as a first-class citizen within our product 🤝 As of this writing, ReadMe is powering docs for over 100,000 OpenAPI documents!
• And this is 100% true… creating songs about OAS* 🎹

*Unless you enjoy bad Maroon 5-esque covers with lots of API puns (no judgment if that’s your thing), we strongly recommend you find another catchy song to blast immediately after listening to avoid this getting stuck in your head as you’re trying to work for the rest of the day on — I don’t know — a blog post about OpenAPI. You’ve been warned.

But let’s set aside the blog posts, code, and song lyrics for a moment and address an OAS-specific piece of content we hadn’t gotten to yet: our application to join the OpenAPI Initiative (OAI), the group that oversees the OAS.

You might have seen this coming based on the title of this post, but I’m proud to announce that we finally took the (clears throat) initiative to join the OAI (and by extension, the Linux Foundation)! To celebrate, we’ve also shipped support for OpenAPI v3.1 in ReadMe, so our customers can take advantage of the latest and greatest in their API Reference. Details on all of this below!

Taking The Initiative

I’m sure many of you are wondering — why did it take so long for ReadMe to join the OAI? Well, the answer is a bit complicated.

ReadMe’s mission is to make documentation and APIs better for everybody. Underpinning everything we do, from big product updates (like the recently redesigned API Reference section and ReadMe Recipes) to the little details (like code samples generated by the api SDK and schema-based tooltips), is the goal of abstracting complexity away and making APIs easier and more fun to use.

Having spent so much time with the OAS ourselves, we initially wanted to shield our users from its complexity. We’ve always believed that people shouldn’t need to know the OAS in order to build great developer hubs on ReadMe.

But as our support for and investment in the OpenAPI ecosystem has grown over the years, we’ve come to realize that the mission of the OAI is quite complementary to our own. In order for us to successfully abstract away the complexity of APIs for our users, we need a few things:

• A complete and thorough understanding of this aforementioned complexity 🤓
• A prescriptive set of standards that we can use as our basis for generating helpful reference documentation 📚
• Ideally a solution that’s vendor-neutral, because nobody likes using separate cables to charge their laptop and their phone ⚡

All of which is to say: we need the OpenAPI community in order to do the work we do, and we’re deeply grateful for it. Joining the OAI today is just one small step in our continued investment in the OpenAPI ecosystem and our broader goals of making APIs easier and more fun to use for everyone. We can’t wait to build and grow alongside other members of the OAI and we’re looking forward to bringing our perspective on developer experience to the group!

3.1 ≈ HTTPie 🥧

Our OpenAPI-related announcements don’t stop there — we’ve also shipped support for OpenAPI v3.1! As part of this update comes a few exciting improvements for API References in ReadMe:

• The ability to upload and validate API specifications that conform to OpenAPI v3.1.0 🚀
• Since 3.1 is a vague approximation for π, it feels fitting that we ship support for HTTPie (as well as regular ol’ HTTP) snippets 🥧
• And last but definitely not least, improved OpenAPI validation and error messages — both within the ReadMe dashboard and via our API 💬

This comes on the heels of support for callback objects, tag objects, and lots of other amazing updates that we’ve been shipping for our API reference over the last few months. Check out our OpenAPI Compatibility Chart for a comprehensive list of our OpenAPI support, and keep an eye on our Changelog for more announcements on this front!

A huge shoutout to everyone at ReadMe that has worked tirelessly to bring these features to our customers. Oh, and if you love working with APIs and the OpenAPI Specification, you should come work with us!