Working with OpenAPI

December 12, 2020
 · 2 min read

Last two years I've been working on various parts of It's a big web application with bunch of services and all of them provide REST API. In order to standardize documentation OpenAPI was chosen as a specification for describing REST API. It's a nice thing and I really see the value in it but the more your service is getting bigger the more complicated become editing of the specification. I found a helpful tool that might interest you.


If you want describe your REST API via OpenAPI you just need create one file in json or yaml formats. Usually it's openapi.json. Having the specification strictly formalized according to a schema opens vast opportunities for code generation. Swagger provides a powerful utility for generating clients on all popular programming languages. I heavily use it in my test automation. Another great feature is a nice human readable documentation that is also automatically generated. Basically it is a good practice to have openapi.json in the same repository where the source code of your service located. During the deploying the specification should be deployed as well. It means that we have to keep the specification up to date. And here we can have some difficulties. Until your service is small it's not a big deal to manually edit the spec. Things are getting more complicated when responses have deep nested objects.


Fortunately, there are many tools for editing openapi.json. I tried several of them and would like to recommend one. It's called Apicurio and it's a nice web based open source designer for your OpenAPI specification. You can upload an existing file or start from the scratch. Apicurio provides ability of collaborative editing. Another cool feature is creating data types from examples. Just paste a response from your application and Apicurio construct a data type. Of course it doesn't work as expected in all cases but it's still very useful. The tool covers almost all OpenAPI schema and even if you cannot do something via UI there is always a tab with raw json. For example there is no way to specify a hashmap so I had to manually write that part. Nevertheless Apicurio made my life a bit easier and I hope it will do yours as well.

diagram 1


Discuss on Github