Some fields exist only on the sample JSON which is displayed under the Example from schema tab and are not mentioned at all on the field list which is displayed under the Schema tab. For example, when we compare the successful operation (200 Response code) documentation, the following two fields are not described in the field list in the schema documentation, yet they are still included in the sample JSON example:
policy.remediable (the remediable entry in the policy object).
reason (in the response JSON root level).
So which is correct, the "dry" schema field list or the sample JSON ?
If the sample is correct, why aren't the additional fields explicitly mentioned in the documentation with's their corresponding types & semantic descriptions ?
Suggested fix
Make sure the API response is properly documented and contains all relevant field both on the schema field list (along with the field names, description, type & structure) and on the sample JSON.
Documentation link
https://pan.dev/prisma-cloud/api/cspm/get-alerts-v-2/
Describe the problem
The response schema documentation is not fully detailed and it is not fully aligned with the given example.
Some object fields are not detailed, for example, the history object documentation just mentions it's an array of the history objects:
However it does not mention the model structure of an history object. It is described only on the sample JSON as such:
Some fields exist only on the sample JSON which is displayed under the Example from schema tab and are not mentioned at all on the field list which is displayed under the Schema tab. For example, when we compare the successful operation (200 Response code) documentation, the following two fields are not described in the field list in the schema documentation, yet they are still included in the sample JSON example:
So which is correct, the "dry" schema field list or the sample JSON ? If the sample is correct, why aren't the additional fields explicitly mentioned in the documentation with's their corresponding types & semantic descriptions ?
Suggested fix
Make sure the API response is properly documented and contains all relevant field both on the schema field list (along with the field names, description, type & structure) and on the sample JSON.