Working with OpenAPI
Last two years I've been working on various parts of cloud.redhat.com. 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.
Specification
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.
Cure
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.
