Docs: CI Lint API documentation does not include full API response in examples

• Start this issue's title with Docs: or Docs feedback:.

Problem to solve

The CI Lint API doc (https://docs.gitlab.com/ee/api/lint.html) describes the request and response properties of the CI Lint API.

The request properties seem to be up to date, but the listed example responses miss two fields that are included in an API response today.

First of all, when making a request to /ci/lint the API returns an object similar to the following:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "merged_yaml": "---\nbuild:\n  stage: Build\n  script:\n  - build\n",
  "includes": [
    {
      "type": "file",
      "location": "template.yml",
      "blob": "https://gitlab.com/namespace/project/-/blob/abcd1234/template.yml",
      "raw": "https://gitlab.com/namespace/project/-/blob/abcd1234/template.yml",
      "extra": {
        "project": "project",
        "ref": "1.2.3"
      },
      "context_project": "current-project",
      "context_sha": "abcd1234"
    }
  ]
}

But the examples miss the includes field. This field is documented in the openAPI spec: https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/openapi/openapi_v2.yaml?plain=1#L52452

The same applies to the jobs field that is returned by the API if a request is made to /ci/lint?include_jobs=true:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "merged_yaml": "---\nbuild:\n  stage: Build\n  script:\n  - build\n",
  "includes": [
    {
      "type": "file",
      "location": "template.yml",
      "blob": "https://gitlab.com/namespace/project/-/blob/abcd1234/template.yml",
      "raw": "https://gitlab.com/namespace/project/-/blob/abcd1234/template.yml",
      "extra": {
        "project": "project",
        "ref": "1.2.3"
      },
      "context_project": "current-project",
      "context_sha": "abcd1234"
    }
  ]
  "jobs": [
    {
      "name": "build",
      "stage": "Build",
      "before_script": [],
      "script": [
        "build"
      ],
      "after_script": [],
      "tag_list": [],
      "only": null,
      "except": null,
      "environment": null,
      "when": "on_success",
      "allow_failure": false,
      "needs": null
    }
  ]
}

Is there a reason for not including those fields in the docs? Or are the examples just not up to date?

Proposal

Extending the examples to include all fields officially exposed / returned by the API.

See also the following discussion on Github: https://github.com/xanzy/go-gitlab/pull/2070