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.