Summary

Our REST API documentation (https://docs.atlassian.com/jira/REST/server/) does provide the schema of the response, but it can be improved to give more information of the response.

For example, the Get Issue has the following response schema

{
    "id": "https://docs.atlassian.com/jira/REST/schema/issue#",
    "title": "Issue",
    "type": "object",
    "properties": {
        "expand": {
            "type": "string"
        },
        "id": {
            "type": "string"
        },
        "self": {
            "type": "string",
            "format": "uri"
        },
        "key": {
            "type": "string"
        },
        "fields": {
            "type": "object",
            "patternProperties": {
                ".+": {}
            },
            "additionalProperties": false
        },
        ...
        ...
        ...
    }
}

This basically means that 'fields' can have any kind of property with any name, which isn't very useful.

Suggestion

Improve the documentation to include more details such as what fields could be returned along with the types and properties, at least for system fields which would always be returned.

The same should be applied for all other response schema. If there are any items which would always be returned, include those in the documentation