Additional documentation of the project?

[timur-han]

Hello,

Is there any documentation of this project somewhere else? The readme.md provided is not comprehensive / self-contained. The configuration effort for a new user is not that less and the documentation is not explanatory for this. One needs to check the actual implementation to understand what is actually meant and it is not always sufficient to get the things working.

[jstoiko]

Looking at the README, I find it quite comprehensive, it may even arguably be too intimidating for a first-time user IMHO.

Personally, I'd like to see more practical examples in the examples/ folder to cover all the features. Is that what you have in mind? If not, can you point-out to what you've had to look in the "actual implementation" that was not in the README?

[timur-han]

In the documentation, you mention:

API documentation Currently disabled
Optionally mount API documentation generated from your RAML definition

I could not find any further information regarding how to do that.

As I experienced a problem with external JSON schemata, I tried to use the following information:

JSON schemas can be added to the application for when external JSON references are needed. From osprey-method-handler.
osprey.addJsonSchema(schema, key)

However, I was not sure if the schema is the path to the schema and what the key was supposed to be as the information was missing. Then I investigated the actually used library and found the information there. However, this solution did not work, as this approach has been probably thought for schemas referenced with URLs.

To make the framework working, I had to start with a really simple RAML file from the scratch and test if it was working in each step, because if there was a failure I could not observe what the problem was. Maybe a configuration failure of mine but in case of an undefined route, no 404 response has been generated but rather it hangs till a timeout:

Undefined API requests will always be rejected with a 404.