The explanation of what a response field is, is currently buried in the ugly fixed-width-font 'schema' section of the docs display. (Personally I would class this as a minor issue, however of the many minor issues with the api console, I'd probably say this is the worst)
This is an area where our old API docs work much better than the RAML API console. It's less important for some more simple API operations, where the example response is fairly self explanatory. But we have some quite complex response structures e.g for our journey planning, where the old docs work a lot better, because you can read a full explanation of how the API works (y'know. API documentation)
Note: The old docs there also hint at nestedness of the different fields. This is a nice-to-have, but not really necessary. A flat list of fields with explanations would be enough to let the user work things out. By fields I mean ideally both the leaf node fields and fields containing a nested structure.
We improved this recently by preventing wrapping in these schema code displays, but the user is still expected to look into an ugly unrendered messy display to read how the API works.
Schema visualisation is logged as issue for mulesoft here: https://github.com/mulesoft/api-console/issues/82 Maybe we can develop a fix as a temporary patch to do some sort of basic rendering of schemas.
The explanation of what a response field is, is currently buried in the ugly
fixed-width-font'schema' section of the docs display. (Personally I would class this as a minor issue, however of the many minor issues with the api console, I'd probably say this is the worst)This is an area where our old API docs work much better than the RAML API console. It's less important for some more simple API operations, where the example response is fairly self explanatory. But we have some quite complex response structures e.g for our journey planning, where the old docs work a lot better, because you can read a full explanation of how the API works (y'know. API documentation)
Note: The old docs there also hint at nestedness of the different fields. This is a nice-to-have, but not really necessary. A flat list of fields with explanations would be enough to let the user work things out. By fields I mean ideally both the leaf node fields and fields containing a nested structure.
We improved this recently by preventing wrapping in these schema code displays, but the user is still expected to look into an ugly unrendered messy display to read how the API works.
Schema visualisation is logged as issue for mulesoft here: https://github.com/mulesoft/api-console/issues/82 Maybe we can develop a fix as a temporary patch to do some sort of basic rendering of schemas.