Have you ever thought of making a programing interface without a clear definition first? If you start writing any program, then it usually starts or goes to a definition of an interaction interface. Whether it is header file for C or interface type for Java - it is a explicitly declared contract how to interact with part of your software.
Now, thinking of existing REST layer for openHAB - it is not based on interfaces other than RESTResource. It does not do a great job with explicit declaration of the interaction interface. Obviously there is always a way - cause you can go to demo.openhab.org and fetch specification from there.
Yet, this will not fly with multiple versions nor with new/old releases making it pretty difficult to utilize this spec. Additionally this resource is, from what I remember, based on introspection which forces you to declare all openapi annotations to influence output of generator. There were cases in the past where due to missing annotations output missed definition of types (i.e. marketplace addon definitions ~ 3.2 release).
Can you share your experiences in this area?