Vanilla's API v2 uses the OpenAPI specification. Are you familiar with it?
Hi devs, I want to start letting people know about stuff the gets developed a little more. We have a lot of code and our newer components are usually quite well documented, but are also often based on open standards that are themselves well documented. Taking the time to read through the standards that we use is going to make you better at working on Vanilla and a better developer in general.
What is the OpenAPI standard?
The OpenAPI standard is a JSON meta document that describes all of the endpoints of an API. It started out as a pet project called Swagger, but became popular enough to become a standard that is well adopted across the Internet. The current version of OpenAPI is 3.0. The Swagger spec is now also referred to as OpenAPI 2.0.
What's so great about the OpenAPI?
The OpenAPI a a JSON document by itself isn't super useful. However, a lot of tools have been written to take advantage of the OpenAPI. The main tool we are using right now is the Swagger UI provides a rich, usable API reference. This means we have full API documentation for our API without having to write that documentation separately. Other tools include API client generators, documentation converters, tooling etc. I encourage you to google Swagger/OpenAPI plus whatever you think you might need to see if there is already a tool for it. I know you will be happy that we have a good
Read the OpenAPI specification!
My big ask here is that you read the OpenAPI specification. If you just use our tools on the surface you will only progress so far in your ability. Understand as many great projects as deeply as possible and you'll start to figure out new ways to knit them together to build great solutions. The more group knowledge we have about great projects and specs in our space the better we'll be as a company.
We still need to implement more of OpenAPI
Currently, we've implemented enough of OpenAPI to get decent documentation. There are still some information we still need to provide. If you go look through the spec and see something that you can think of that would be super useful, let me know.