cmd-johnson
commented
7 years ago Turns out inheritance and polymorphism isn't handled too well by Swagger and while the RAML 1.0 specification allows to do that quite well, osprey only really supports RAML 0.8 at the moment. However osprey looks like it's being worked on, so I'll just wait until they are ready to incorporate the API specification into the server and continue documenting it manually until then.
Create a formal definition of all API routes, including parameters and return values. At a first glance, Swagger or RAML look quite decent and both provide middleware for express for validating user inputs and optionally response bodies.