Incomplete models

[vdachev]

Request/response/data models is not complete. In Swagger there is a "Model" and a "Model Schema" both representing the data in a uniform and complete way. Here, composite objects are not well-documented, as they're displayed as a table, no hierarchy there.

For example:

• http://doc.ozwillo.com/#s3-1-ozwillo-request , "Request Body" What is a "User object", and what is a "Organization object"?
• http://doc.ozwillo.com/#s3-3-provider-acknowledgement , "Request Body" Why "array of NeededScope objects", not "NeededScope[]"?
• http://doc.ozwillo.com/#s5-api-notifications Where is "Request Body"? Should be "Response Body" described as in a book "The response is a JSON Array of messages, each with the following fields... [table follows]"?

[silently]

First point fixed by https://github.com/ozwillo/ozwillo-doc/commit/57691c541d44a1597b6465a8510365058c01abde

For the second, yes why not being more concise, @tbroyer why do you prefer between [NeededScope], NeededScope[] or a variant?

For the third one, no "Request body" means.... no request body ;) (and http://doc.ozwillo.com/#s5-get-n-id-messages is a GET request)

[tbroyer]

I find array of NeededScope objects a bit clearer than NeededScope[] but don't have a strong opinion, and it's a subjective matter anyway (and as such would prefer not spending any time changing things that are not "broken")

[vdachev]

@silently my bad, about the last one. But still, if there's no body of a POST request, it's nice to be stated explicitly, rather than thinking the documentation is incomplete.

@tbroyer the problem is not in "Array of ..." itself but the different way structured objects are described. In some (http://doc.ozwillo.com/#response-body) you have a table describing a plain object (again, no hierarchy as in Swagger, there), and in others (http://doc.ozwillo.com/#s5-get-apps-instance-id-services) it's a text description. As I said, I personally find Swagger's way of representing request and response data more detailed and informative.

[tbroyer]

See http://doc.ozwillo.com/#s5-get-n-id-messages to understand the state of http://doc.ozwillo.com/#s5-get-apps-instance-id-services (using a link instead of repeating a table), the thing being: how would you say that the response is an array? But as I said elsewhere (mail?) I don't really care myself one way or another.

[vdachev]

@tbroyer , I do find an understand the documentation. I just gave Swagger UI an example of, IMHO, a clearer and more visual way to represent the objects in the requests and responses. It also allows to copy 'n paste it in a Javascript, do a few replacements and you're in the game.

As you pointed out though, it's a matter of personal preference.