OAS 3.0

For the past 5 days, I have writing lines and more lines of API specification so the implementation could then be started. Without a specification, there is no way you can develop anything without a lot of back and forth to ensure that the endpoint is working as expected.

If you haven’t written an API specification before you will notice that it can be quite a challenge. You must find a way to properly inform how it will work and find a way to present that information and the best of all, the correct way of doing it is doing it ahead of time. Similar to TDD (test driven development) where you write your tests first and then develop.

While looking for ways to dynamically render the documentation on the web I came across the OpenAPI 3.0 specification, former Swagger, that provides in a very simple way a pre-defined standard to write the specification in a way that could work with any language and tools to render this specification.

In gist what you are doing is writing a huge yaml file that will hold all of the API behavior and this yaml file will have, among other portions, the following:

  • API Info: Will hold the information about servers, contact, license etc.
  • Objects: that are used as a reference through the whole specification.
  • Paths: that is what will become the endpoints of your API and will very likely generate and make use of objects.

Swagger provides an editor that will provide a visualization of the specification and will also perform proper parsing to ensure that all is correct. This editor is a great place to start because it will give you a way to parse and visualize the initial specification, but after a while then it will be used mainly to parse the specification for errors. The Docker image that is available with the editor is very useful during this phase.

After the specification is completed, things become interesting. The OpenAPI specification can now be used with tools that will actually render an SDK and tools that will render a documentation (such as ReDoc) based on that same yaml file that holds the whole API specification.

Not everything is perfect. This is still an open source project and needs some fine tuning, but the potential is surely there.