github / rest-api-description

An OpenAPI description for GitHub's REST API

GitHub's REST API OpenAPI Description

This repository contains OpenAPI descriptions for GitHub's REST API.

What is OpenAPI?

From the OpenAPI Specification:

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Project Status

As of the 1.1.4 release, this description is considered stable and generally available.

The descriptions folder contains the 3.0 version of the description. The descriptions-next folder contains the 3.1 version of the description, and is subject to breaking changes on the main branch.

Description Formats

Each OpenAPI document is available in two formats: bundled and dereferenced.

• The bundled descriptions are single file artifacts that make usages of OpenAPI components for reuse and portability. This is the preferred way of interacting with GitHub's OpenAPI description.
• Certain tools have poor support for references to components within the artifact. We highly encourage to look into tooling that supports referenced components, but since that's not always possible, we also provide a fully dereferenced version of the description as well, without any references.

Vendor Extensions

We use various vendor extensions for concepts that are harder to express with OpenAPI components and/or are specific to GitHub. For more information on the extensions used in these description, check out extensions.md

Limitations

• Not all headers are described in the OpenAPI documents, expect those to be added over time.
• Certain GitHub API resources use multi segment path parameters, which aren't supported by the OpenAPI specification. For the time being, we have annotated such parameters with a x-multi-segment extension. In general, URL encoding those parameters is a good idea.
• A lot of operations described in these documents are accessible through multiple paths. For the time being we have described the most common way to access these operations, but are working on a way to describe alias paths and/or describe all possible paths.
• This repository only contains the bundled and dereferenced versions of our REST API descriptions. We're looking into offering a fully referenced directory structure for easier browsing.

Contributing

Because this description is used across GitHub's whole API development experience, we don't currently accept pull requests that directly modify the description. This repository is automatically kept up to date with the description used to validate GitHub API requests as well as powering contract tests. See CONTRIBUTING.md for more details.

If you've identified a mismatch between GitHub API's behavior and these descriptions, or found an issue with the format of a schema, please open an issue.

License

github/rest-api-description is licensed under the MIT license

Contact

You may contact [email protected] with any questions related to this repository.

rest-api-description's Issues

'servers' not part of api state

'servers' are separate from request/response state. They are architecture/networking and should be contained in separate YAML/XML doc as they do not need to be shared with all components sharing api request/response.

'Servers' is more aligned with CORS whitelisting/blacklisting and architectural awareness for the component pieces and is often handled by Zookeeper and other software.

This is a redundant piece and not necessary.

[Schema Inaccuracy] Description regressions

Schema Inaccuracy

the latest update brought back the filler descriptions for parameters, e.g. "secret_name parameter" for the secret_name parameter. github/openapi did remove these filler descriptions.

Also for ref in git/list-matching-refs the description is ref+ parameter, but the {ref+} URL parameter no longer exists, it's just {ref} now. Same with path+ parameter, branch+ parameter

actions/delete-self-hosted-runner-from-repo

• "scope to use this endpoint." is missing at the end of the operation description

actions/getself-hosted-runner-for-repo

• "endpoint." is missing at the end of the operation description

repos/create-dispatch-event (event_type parameter)

• Description says event_type parameter is required, but schema says it's not.

repos/create-pages-site

• Description removed: "The source branch and directory used to publish your Pages site." Just want to make sure this was not a mistake

Reproduction Steps

n/a

[Schema Inaccuracy] Some operations have a category of "code-scanning." (with a trailing period)

Schema Inaccuracy

Notice the . at the end of these:

Permalink example (that doesn't render the problematic line on GitHub because the file is too big):

https://github.com/github/rest-api-description/blob/afe23f43cbb315010f9bcda9edd53a588412d1ac/descriptions/ghes-2.22/ghes-2.22.json#L21735-L21736

Expected

Should probably be code-scanning

cc @github/docs-content-ecosystem @github/ecosystem-api

[Schema Inaccuracy] Duplicate line.

Schema Inaccuracy

This extra line needs to be removed.
The current version before the PR -> https://docs.github.com/en/free-pro-team@latest/rest/reference/repos#create-a-deployment--parameters

I made a PR github/docs/pull/2471 since I didn't know that the specifications could not be directly edited.

mercy preview not mentioned for repository REST endpoints

What article on docs.github.com is affected?

https://docs.github.com/en/free-pro-team@latest/rest/reference/repos#list-organization-repositories
Returns a listing of repositories for an org/user. The example shown in the docs displays a "topics" key in the data, but does not show up when making the actual API call

What part(s) of the article would you like to see updated?

Ideally the "topics" data would be added to the actual API, like the docs describe...

Additional information

[Schema Inaccuracy] Enum with no values

There is an enum property with no values on line 39407

DELETE operation on /users/{username}/suspended missing path param

Hi,

I validated the API def with SwaggerHub and it (correctly IMO) found an error:

Your path parameter needs to either be added into the DELETE operation (its currently only on PUT) or better still move it outside of the PUT operation and it is then shared by all of the operations on that path (PUT and DELETE)
FROM:

TO:

This will remove the OAS3 validation error.

[Schema Inaccuracy] <Describe Problem>

Schema Inaccuracy

Expected

Reproduction Steps

How to create new branch that is empty using GitHub REST API?

Hi Team,

I want to put new files in my repository TestRepoSandeep. This repo has a master branch that already contains few files. I want to create a new branch test and commit new files there. This new branch should not contain any files from master. I am trying to create an empty branch but could not figure out how to do this using GitHub REST API and Python.

Please suggest.

[Schema Inaccuracy] Commit compare endpoint limits the number of files returned

Schema Inaccuracy

The /repos/{owner}/{repo}/compare/{base}...{head} endpoint has an undocumented limit on the number of files it returns (300).

Expected

There would either be no limit on the number of files returned, or there would be a way to paginate them.

Reproduction Steps

For example, see facebook/react@v16.10.2...v16.12.0 - there are 366 files changes between these 2 tags.

If you access the API:

$ curl -sS https://api.github.com/repos/facebook/react/compare/v16.10.2...v16.12.0 | jq -r '.files | length'

outputs

300

Only the first 300 files affected are returned in the response.

[Schema Inaccuracy] Incorrect enum for workflow-run-status

Schema Inaccuracy

      "workflow-run-status": {
        "name": "status",
        "description": "Returns workflow runs associated with the check run `status` or `conclusion` you specify. For example, a conclusion can be `success` or a status can be `completed`. For more information, see the `status` and `conclusion` options available in \"[Create a check run](https://docs.github.com/rest/reference/checks#create-a-check-run).\"",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "enum": ["completed", "status", "conclusion"]
        }
      },

Expected

I'm not sure what all the possible values can be, but I'm quite sure that it should include "in_progress" and not include "status" or "conclusion"

Reproduction Steps

Compare example response at https://docs.github.com/en/free-pro-team@latest/rest/reference/checks#create-a-check-run

[Schema Inaccuracy] Invalid examples reported by Spectral

Schema Inaccuracy

I know you lot use Spectral for some internal stuff, and I wanted to let you know we've been working on a new feature that lets you know when examples are invalid against their defined schema (stoplightio/spectral#1284). It looks like there's quite a few invalid examples in this repo, so I figured I should give you a heads up to resolve them before you upgrade and have to fix things in a rush.

Expected

I'd expect none of these errors to be here. (Some are showing up twice and we're investigating why, and some of the errors are a little hard to read and we're working on that too).

It's because the enum is only showing uploaded, and then the example is open.

        state:
          description: State of the release asset.
          type: string
          enum:
          - uploaded
          example: open

I'd ditch that example and put it in the enum. Most tooling will take an enum value and use it as an example if a property doesn't have one (especially ReDoc, which you mentioned in the README.md).

        state:
          description: State of the release asset.
          type: string
          enum:
          - uploaded
          - open

Simple enough fix right?

Reproduction Steps

Clone spectral.

$ gco fix/support-examples-validation
$ yarn
$ yarn build
$ yarn cli lint {path-to-this-repo}/descriptions/api.github.com/api.github.com.yaml

[Question] Getting users and repos by legacy databaseId

Are there any plans to document endpoints starting with /user/{user_id} and /repositories/{repo_id}?

[Schema Inaccuracy] Spelling mistake

Spelling mistake here. Found by https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker

[Schema Inaccuracy] Incorrect description for project/create-card operation

Schema Inaccuracy

The description for the project/create-card operation is incorrect. The description talks about issues and pull requests, and does not mention project cards at all.

Expected

The description should describe what creating a project card entails, rather than describe issues and pull requests.

Current

The current description shows:

post": {
        "summary": "Create a project card",
        "description": "**Note**: GitHub's REST API v3 considers every pull request an issue, but not every issue is a pull request. For this reason, \"Issues\" endpoints may return both issues and pull requests in the response. You can identify pull requests by the `pull_request` key.\n\nBe aware that the `id` of a pull request returned from \"Issues\" endpoints will be an _issue id_. To find out the pull request id, use the \"[List pull requests](https://docs.github.com/rest/reference/pulls#list-pull-requests)\" endpoint.",
        "tags": [
          "projects"
        ],
        "operationId": "projects/create-card",
        "externalDocs": {
          "description": "API method documentation",
          "url": "https://docs.github.com/rest/reference/projects#create-a-project-card"
        },
       ...

[Schema Inaccuracy] Issues parsing api.github.com.yaml

Schema Inaccuracy

Failure to parse api.github.com.yaml using node.js yaml module.

Multi-line single-quoted string needs to be sufficiently indented at line 30137, column 24:
Multi-line single-quoted string needs to be sufficiently indented at line 58993, column 18

Expected

The YAML file parses with a spec. compliant YAML parser.

Reproduction Steps

npm i swagger2openapi
boast https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.yaml

[Schema Inaccuracy] Incorrect type for workflow_id

follow up to https://github.com/octokit/rest.js/issues/1885 /cc @yfried

Schema Inaccuracy

The workflow_id URL parameter is described as integer.

    workflow-id:
      name: workflow_id
      in: path
      required: true
      schema:
        type: integer

Expected

The description at https://docs.github.com/en/rest/reference/actions#create-a-workflow-dispatch-event states

You can also replace {workflow_id} with the workflow file name. For example, you could use main.yml.

Which I understand means that workflow_id can also be set to a string

Reproduction Steps

I tried to create an actions dispatch event using curl and a workflow file name, but got a 404. Did miss something or are the docs incorrect?

curl -XPOST -H"Authorization: token [TOKEN]" https://api.github.com/repos/octokit/sandbox/actions/workflows/nodekitten.yml/dispatches -d '{"ref": "main"}'  

[Schema Inaccuracy] incorrect requestBody schema for branch protection endpoints

Schema Inaccuracy

These endpoints now accept a namespaced array in the request body, as documented:

• Add status check contexts (POST /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts)
  https://docs.github.com/rest/reference/repos#add-status-check-contexts
• Set status check contexts (PUT /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts)
  https://docs.github.com/rest/reference/repos#set-status-check-contexts
• Remove status check contexts (DELETE /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts)
  https://docs.github.com/rest/reference/repos#remove-status-check-contexts
• Add app access restrictions (POST /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps)
  https://docs.github.com/rest/reference/repos#add-app-access-restrictions
• Set app access restrictions (PUT /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps)
  https://docs.github.com/rest/reference/repos#set-app-access-restrictions
• Remove app access restrictions (DELETE /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps)
  https://docs.github.com/rest/reference/repos#remove-app-access-restrictions
• Add team access restrictions (POST /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams)
  https://docs.github.com/rest/reference/repos#add-team-access-restrictions
• Set team access restrictions (PUT /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams)
  https://docs.github.com/rest/reference/repos#set-team-access-restrictions
• Remove team access restrictions (DELETE /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams)
  https://docs.github.com/rest/reference/repos#remove-team-access-restrictions
• Add user access restrictions (POST /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users)
  https://docs.github.com/rest/reference/repos#add-user-access-restrictions
• Set user access restrictions (PUT /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users)
  https://docs.github.com/rest/reference/repos#set-user-access-restrictions
• Remove user access restrictions (DELETE /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users)
  https://docs.github.com/rest/reference/repos#remove-user-access-restrictions

but the schema for these endpoints is currently defined as

        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "description": "contexts parameter",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        },

Expected

the schema should instead be an object with a single property, e.g.

        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contexts": {
                    "type": "array",
                    "description": "...",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              },
              "example": {
                "labels": [
                  "ci-test",
                  "linter"
                ]
              }
            }
          }
        },

Reproduction Steps

See curl examples in the docs linked above

[Question] What about webhooks/event payloads?

Are there any plans to include an openapi specification for event payloads described in:

https://developer.github.com/webhooks/event-payloads/

Have a nice day!

[Schema Inaccuracy] nullable used in an odd (probably inaccurate) way

Schema Inaccuracy

The POST request body schema at /gists defines oneOf the options for the public property to be nullable: true (without any type or enum restrictions).

This means "any type of thing, and it could be null" whereas I can only imagine the intention was simply to state "you are allowed to pass null in addition to a boolean or the strings 'true'/'false'."

From a human readability perspective, this is not really so bad -- I've picked the only interpretation that makes sense to me. From a tooling perspective, this makes a big difference. A tool cannot verify input or offer the user good code generation based on the knowledge that "any type of thing is allowed here."

Expected

To specify that null is one of the options without also allowing literally any type of input, I would at least expect to see

- nullable: true
  enum:
    - null

which would say "any type of thing, as long as that thing is null."

Really, I am not clear on why the enclosing definition is not simply

oneOf:
- description: Flag indicating whether the gist is public
  example: true
  type: boolean
- type: string
  nullable: true
  enum:
  - 'true'
  - 'false'
  - null

Which would allow for null values as part of the string option without adding the extra case.

[Schema Inaccuracy] Incorrect operationId

Schema Inaccuracy

Originally reported by @gr2m in https://github.com/github/openapi/issues/340:

https://github.com/github/openapi/blob/fdd3f34435dc90c0db37126c795bc74f4076d820/definitions/operations/repos/update-status-check-potection.yml#L12

This should be repos/update-status-check-protection

- repos/update-status-check-potection
+ repos/update-status-check-protection

I'd be happy to send a pull request but I see the operationID show up in many files, and I'm not sure which need to be changed and which get updated automagically.

Also this needs a new entry in x-githubBreakingChanges:

  - type: operation
    date: '2020-07-29'
    note: '"repos/update-status-check-potection" operation ID is now "repos/update-status-check-protection"'
    before:
      operationId: repos/update-status-check-potection
    after:
      operationId: repos/update-status-check-protection

And the existing entry should be update, because it does actually not have the typo

  - type: operation
    date: '2020-06-04'
-   note: '"repos/update-protected-branch-required-status-checks" operation ID is now "repos/update-status-checks-protection"'
+   note: '"repos/update-protected-branch-required-status-checks" operation ID is now "repos/update-status-checks-potection"'
    before:
      operationId: repos/update-protected-branch-required-status-checks
    after:
-     operationId: repos/update-status-checks-protection
+     operationId: repos/update-status-checks-potection

[Schema Inaccuracy] 'components/schemas/file-commit' is missing "required" key

Schema Inaccuracy

The content and and commit properties are always present. The same is true for all other sub-properties.

Also content is set as "nullable": true, but that is only true for the "DELETE" operation.

      "file-commit": {
        "title": "File Commit",
        "description": "File Commit",
        "type": "object",
        "properties": {
          "content": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "path": { "type": "string" },
              "sha": { "type": "string" },
              "size": { "type": "integer" },
              "url": { "type": "string" },
              "html_url": { "type": "string" },
              "git_url": { "type": "string" },
              "download_url": { "type": "string" },
              "type": { "type": "string" },
              "_links": {
                "type": "object",
                "properties": {
                  "self": { "type": "string" },
                  "git": { "type": "string" },
                  "html": { "type": "string" }
                }
              }
            },
            "nullable": true
          },
          "commit": {
            "type": "object",
            "properties": {
              "sha": { "type": "string" },
              "node_id": { "type": "string" },
              "url": { "type": "string" },
              "html_url": { "type": "string" },
              "author": {
                "type": "object",
                "properties": {
                  "date": { "type": "string" },
                  "name": { "type": "string" },
                  "email": { "type": "string" }
                }
              },
              "committer": {
                "type": "object",
                "properties": {
                  "date": { "type": "string" },
                  "name": { "type": "string" },
                  "email": { "type": "string" }
                }
              },
              "message": { "type": "string" },
              "tree": {
                "type": "object",
                "properties": {
                  "url": { "type": "string" },
                  "sha": { "type": "string" }
                }
              },
              "parents": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "url": { "type": "string" },
                    "html_url": { "type": "string" },
                    "sha": { "type": "string" }
                  }
                }
              },
              "verification": {
                "type": "object",
                "properties": {
                  "verified": { "type": "boolean" },
                  "reason": { "type": "string" },
                  "signature": { "type": "string", "nullable": true },
                  "payload": { "type": "string", "nullable": true }
                }
              }
            }
          }
        }
      },

Expected

For every "properties" key there should be a sibling "required" key which has all the "properties.*" keys as array values

Reproduction Steps

https://runkit.com/gr2m/github-rest-api-description-107

> PUT /repos/{owner}/{repo}/contents/{path}
  owner: gr2m
  repo: sandbox
  path: test-file.txt
  content: 
  message: create test-file.txt

< 201

  {
    "content": {
      "name": "test-file.txt",
      "path": "test-file.txt",
      "sha": "e69de29bb2d1d6434b8b29ae775ad8c2e48c5391",
      "size": 0,
      "url": "https://api.github.com/repos/gr2m/sandbox/contents/test-file.txt?ref=main",
      "html_url": "https://github.com/gr2m/sandbox/blob/main/test-file.txt",
      "git_url": "https://api.github.com/repos/gr2m/sandbox/git/blobs/e69de29bb2d1d6434b8b29ae775ad8c2e48c5391",
      "download_url": "https://raw.githubusercontent.com/gr2m/sandbox/main/test-file.txt",
      "type": "file",
      "_links": {
        "self": "https://api.github.com/repos/gr2m/sandbox/contents/test-file.txt?ref=main",
        "git": "https://api.github.com/repos/gr2m/sandbox/git/blobs/e69de29bb2d1d6434b8b29ae775ad8c2e48c5391",
        "html": "https://github.com/gr2m/sandbox/blob/main/test-file.txt"
      }
    },
    "commit": {
      "sha": "9ad620d255316849b668b5ca969bcd1f3821f1b9",
      "node_id": "MDY6Q29tbWl0MTAyOTg1NDcwOjlhZDYyMGQyNTUzMTY4NDliNjY4YjVjYTk2OWJjZDFmMzgyMWYxYjk=",
      "url": "https://api.github.com/repos/gr2m/sandbox/git/commits/9ad620d255316849b668b5ca969bcd1f3821f1b9",
      "html_url": "https://github.com/gr2m/sandbox/commit/9ad620d255316849b668b5ca969bcd1f3821f1b9",
      "author": {
        "name": "Gregor Martynus",
        "email": "[email protected]",
        "date": "2020-12-02T00:05:29Z"
      },
      "committer": {
        "name": "Gregor Martynus",
        "email": "[email protected]",
        "date": "2020-12-02T00:05:29Z"
      },
      "tree": {
        "sha": "5158239c6cade718e809cde7301aca56d72fd228",
        "url": "https://api.github.com/repos/gr2m/sandbox/git/trees/5158239c6cade718e809cde7301aca56d72fd228"
      },
      "message": "create test-file.txt",
      "parents": [
        {
          "sha": "a2538ba05b2049e32e5d2caf8c0f8a2427a68512",
          "url": "https://api.github.com/repos/gr2m/sandbox/git/commits/a2538ba05b2049e32e5d2caf8c0f8a2427a68512",
          "html_url": "https://github.com/gr2m/sandbox/commit/a2538ba05b2049e32e5d2caf8c0f8a2427a68512"
        }
      ],
      "verification": {
        "verified": false,
        "reason": "unsigned",
        "signature": null,
        "payload": null
      }
    }
  }

> PUT /repos/{owner}/{repo}/contents/{path}
  owner: gr2m
  repo: sandbox
  path: test-file.txt
  content: 
  sha: e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
  message: update test-file.txt

< 200

  {
    "content": {
      "name": "test-file.txt",
      "path": "test-file.txt",
      "sha": "e69de29bb2d1d6434b8b29ae775ad8c2e48c5391",
      "size": 0,
      "url": "https://api.github.com/repos/gr2m/sandbox/contents/test-file.txt?ref=main",
      "html_url": "https://github.com/gr2m/sandbox/blob/main/test-file.txt",
      "git_url": "https://api.github.com/repos/gr2m/sandbox/git/blobs/e69de29bb2d1d6434b8b29ae775ad8c2e48c5391",
      "download_url": "https://raw.githubusercontent.com/gr2m/sandbox/main/test-file.txt",
      "type": "file",
      "_links": {
        "self": "https://api.github.com/repos/gr2m/sandbox/contents/test-file.txt?ref=main",
        "git": "https://api.github.com/repos/gr2m/sandbox/git/blobs/e69de29bb2d1d6434b8b29ae775ad8c2e48c5391",
        "html": "https://github.com/gr2m/sandbox/blob/main/test-file.txt"
      }
    },
    "commit": {
      "sha": "3638174994d1300afa4b546569137d8ef4017f8a",
      "node_id": "MDY6Q29tbWl0MTAyOTg1NDcwOjM2MzgxNzQ5OTRkMTMwMGFmYTRiNTQ2NTY5MTM3ZDhlZjQwMTdmOGE=",
      "url": "https://api.github.com/repos/gr2m/sandbox/git/commits/3638174994d1300afa4b546569137d8ef4017f8a",
      "html_url": "https://github.com/gr2m/sandbox/commit/3638174994d1300afa4b546569137d8ef4017f8a",
      "author": {
        "name": "Gregor Martynus",
        "email": "[email protected]",
        "date": "2020-12-02T00:05:30Z"
      },
      "committer": {
        "name": "Gregor Martynus",
        "email": "[email protected]",
        "date": "2020-12-02T00:05:30Z"
      },
      "tree": {
        "sha": "5158239c6cade718e809cde7301aca56d72fd228",
        "url": "https://api.github.com/repos/gr2m/sandbox/git/trees/5158239c6cade718e809cde7301aca56d72fd228"
      },
      "message": "update test-file.txt",
      "parents": [
        {
          "sha": "9ad620d255316849b668b5ca969bcd1f3821f1b9",
          "url": "https://api.github.com/repos/gr2m/sandbox/git/commits/9ad620d255316849b668b5ca969bcd1f3821f1b9",
          "html_url": "https://github.com/gr2m/sandbox/commit/9ad620d255316849b668b5ca969bcd1f3821f1b9"
        }
      ],
      "verification": {
        "verified": false,
        "reason": "unsigned",
        "signature": null,
        "payload": null
      }
    }
  }

> DELETE /repos/{owner}/{repo}/contents/{path}
  owner: gr2m
  repo: sandbox
  path: test-file.txt
  sha: e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
  message: delete test-file.txt

< 200

  {
    "content": null,
    "commit": {
      "sha": "61267676458918db757f0a6ebdd2c5376837ef8e",
      "node_id": "MDY6Q29tbWl0MTAyOTg1NDcwOjYxMjY3Njc2NDU4OTE4ZGI3NTdmMGE2ZWJkZDJjNTM3NjgzN2VmOGU=",
      "url": "https://api.github.com/repos/gr2m/sandbox/git/commits/61267676458918db757f0a6ebdd2c5376837ef8e",
      "html_url": "https://github.com/gr2m/sandbox/commit/61267676458918db757f0a6ebdd2c5376837ef8e",
      "author": {
        "name": "Gregor Martynus",
        "email": "[email protected]",
        "date": "2020-12-02T00:05:31Z"
      },
      "committer": {
        "name": "Gregor Martynus",
        "email": "[email protected]",
        "date": "2020-12-02T00:05:31Z"
      },
      "tree": {
        "sha": "57785e0b83c65b8320ef0f48b42e406a175984d2",
        "url": "https://api.github.com/repos/gr2m/sandbox/git/trees/57785e0b83c65b8320ef0f48b42e406a175984d2"
      },
      "message": "delete test-file.txt",
      "parents": [
        {
          "sha": "3638174994d1300afa4b546569137d8ef4017f8a",
          "url": "https://api.github.com/repos/gr2m/sandbox/git/commits/3638174994d1300afa4b546569137d8ef4017f8a",
          "html_url": "https://github.com/gr2m/sandbox/commit/3638174994d1300afa4b546569137d8ef4017f8a"
        }
      ],
      "verification": {
        "verified": false,
        "reason": "unsigned",
        "signature": null,
        "payload": null
      }
    }
  }

[Schema Inaccuracy] Incorrect "required" key

Schema Inaccuracy

https://github.com/github/rest-api-description/blob/a6c95e025223022e1522b7e6e6ed32d08aa8dd9e/descriptions/api.github.com/api.github.com.json#L50682-L50684

JSON path: components.schemas.event.properties.payload.properties.pages.required

This refers to an array type schema, which should not have the required key. Are these three lines supposed to be moved two lines down (i.e. applied on event.properties.payload) or one line up (i.e. applied on event.properties.payload.pages.items?

[Schema Inaccuracy] Add description for all path parameters

Schema Inaccuracy

These path parameters are missing descriptions

• repo
• owner
• ref
• check_run_id
• content_reference_id

These were reported by @hmharvey:

• sha
• ref
• path
• name
• team_slug
• discussion_number
• comment_number
• username
• assignee
• archive_format
• issue_number
• milestone_number
• source
• pull_number
• tag

There are also a lot of id parameters without descriptions, and while these aren't as big of a concern when generating, would still be nice for completeness:

• gist_id
• thread_id
• team_id
• reaction_id
• card_id
• column_id
• project_id
• check_run_id
• check_suite_id
• app_id
• status_id
• deployment_id
• hook_id
• event_id
• build_id
• comment_id
• release_id
• asset_id

Additionally, there are a few parameters that also show up with descriptions like name parameter. It would be great if these descriptions were more descriptive like The name of x. These parameters are:

• release_id
• name
• label

And to be fully transparent, this is from a few releases back so sorry if any of these have changed since! A linting rule I'm sure would help ✨

[Schema Inaccuracy] Verification object is included as description instead of parameters

Schema Inaccuracy

The description of the verification object is included in some operations, but it is very long:

• https://help.github.com/en/rest/reference/git#get-a-tag
• https://help.github.com/en/rest/reference/git#create-a-tag-object
• https://help.github.com/en/rest/reference/git#create-a-commit
• https://help.github.com/en/rest/reference/git#get-a-commit

The first table is missing. For example, the old docs are displayed like this:

We should add these response values to the schema and then display the collapsed schema rather than including this in the description.

[Schema Inaccuracy] Some operations have a category of "code-scanning/

Schema Inaccuracy

Expected

Reproduction Steps

[Schema Inaccuracy] Incorrect type for default property

Schema Inaccuracy

At #/paths/~1repos~1{owner}~1{repo}~1actions~1workflows~1{workflow_id}~1dispatches/post/requestBody/content/application~1json/properties/inputs/default

Expected

expected 'object' to be 'string'

It looks like the default property contains a continuation of the description property, and not an object type default for this schema.

                inputs:
                  type: object
                  description: Input keys and values configured in the workflow file.
                    The maximum number of properties is 10.
                  default: Any default properties configured in the workflow file
                    will be used when `inputs` are omitted.
                  additionalProperties:
                    type: string
                  maxProperties: 10

From the OpenAPI Specification:

default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.

Reproduction Steps

npm i -g swagger2openapi
boast github.json

[Schema Inaccuracy] Single source global hook descriptions.

Schema Inaccuracy

Originally reported by @lucascosti - https://github.com/github/openapi/issues/255

Expected

For enterprise global webhooks, the config key is common across the Create a global webhook and Update a global webhook endpoints, but it is copied as the same content for both in the operation files.

It would be good to abstract this description out into a parameter file that is used by both.

[Schema Inaccuracy] workflow-run fields should not be nullable

Schema Inaccuracy

workflow-run created_at & updated_at are nullable, I don't see why they can be null.

Expected

They shouldn't be.

Reproduction Steps

new Date(workflow_run.created_at)

  Overload 1 of 5, '(value: string | number | Date): Date', gave the following error.
    Argument of type 'string | null' is not assignable to parameter of type 'string | number | Date'.
      Type 'null' is not assignable to type 'string | number | Date'.

[Schema Inaccuracy] <Describe Problem>

Schema Inaccuracy

Expected

Reproduction Steps

[Schema Inaccuracy] "issue-simple" schema's "labels" items properties are defined as optional

Schema Inaccuracy

The labels item properties are all defined as optional in #/components/schemas/issue-simple

"issue-simple": {
  "title": "Issue Simple",
  "description": "Issue Simple",
  "type": "object",
  "properties": {
    ...
    "labels": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "node_id": { "type": "string" },
          "url": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string", "nullable": true },
          "color": { "type": "string" },
          "default": { "type": "boolean" }
        }
      }
    },
},

Expected

The should all be defined as required. I think that #/components/schemas/label has the correct schema already, so maybe the best change would be

"issue-simple": {
  "title": "Issue Simple",
  "description": "Issue Simple",
  "type": "object",
  "properties": {
    ...
    "labels": {
      "type": "array",
      "items": { "$ref": "#/components/schemas/label" }
    },
},

Reproduction Steps

curl https://api.github.com/repos/github/rest-api-description/issues/109 | jq '.labels'
[
  {
    "id": 2231940444,
    "node_id": "MDU6TGFiZWwyMjMxOTQwNDQ0",
    "url": "https://api.github.com/repos/github/rest-api-description/labels/Inaccuracy",
    "name": "Inaccuracy",
    "color": "f94050",
    "default": false,
    "description": ""
  }
]

[Schema Inaccuracy] Error codes are function; cannot be internationalized

Schema Inaccuracy

Error codes are a holdover from Swagger and should not be included in state document.

They cannot be internationalized and are provided by 'function'; they are not static.

Expected

Function provides these codes and if ANYTHING, you can provide CHECKS based upon expected codes but not the actual codes and responses because that would imply that the document is now responsible for internationalization.

[Schema Inaccuracy] Catch empty descriptions

Schema Inaccuracy

Can we add a check to ensure that no parameter descriptions are missing. This is related to #124.

From a previous issue when we used the openapi repo, it was mentioned that:

you can enable this rule by enabling parameter-description rule in the Redoc.ly CLI.

For more built-in rules see: https://redoc.ly/docs/cli/built-in-rules/#parameter-description

[Schema Inaccuracy] List of success response schemas lacking "required" keys

Follow up to #106 and #107

As discussed with @xuorig I'll create separate issues for each case where the response schemas are lacking a "required" key. Some might be falso positive, I'll go through them one-by-one, but here is a list based on the latest api.github.com.deref.json file

126 operations are lacking "required" key in success response schemas

Issues Created

• #106 POST /app/installations/{installation_id}/access_tokens (apps/create-installation-access-token)
• #107 PUT /repos/{owner}/{repo}/contents/{path} (repos/create-or-update-file-contents)
• #107 DELETE /repos/{owner}/{repo}/contents/{path} (repos/delete-file)

To be reviewed

(sorted by priority based on my best judgement)

apps

• GET /installation/repositories (apps/list-repos-accessible-to-installation)
• GET /orgs/{org}/installations (orgs/list-app-installations)
• GET /user/installations (apps/list-installations-for-authenticated-user)
• GET /user/installations/{installation_id}/repositories (apps/list-installation-repos-for-authenticated-user)

statuses and checks

• GET /repos/{owner}/{repo}/commits/{ref}/statuses (repos/list-commit-statuses-for-ref)
• POST /repos/{owner}/{repo}/statuses/{sha} (repos/create-commit-status)
• PATCH /repos/{owner}/{repo}/check-suites/preferences (checks/set-suites-preferences)
• GET /repos/{owner}/{repo}/check-suites/{check_suite_id}/check-runs (checks/list-for-suite)
• GET /repos/{owner}/{repo}/commits/{ref}/check-suites (checks/list-suites-for-ref)
• GET /repos/{owner}/{repo}/commits/{ref}/check-runs (checks/list-for-ref)

search

• GET /search/code (search/code)
• GET /search/commits (search/commits)
• GET /search/issues (search/issues-and-pull-requests)
• GET /search/labels (search/labels)
• GET /search/repositories (search/repos)
• GET /search/topics (search/topics)
• GET /search/users (search/users)

actions

• GET /orgs/{org}/actions/permissions (actions/get-github-actions-permissions-organization)
• GET /orgs/{org}/actions/permissions/repositories (actions/list-selected-repositories-enabled-github-actions-organization)
• GET /orgs/{org}/actions/permissions/selected-actions (actions/get-allowed-actions-organization)
• GET /orgs/{org}/actions/runner-groups (actions/list-self-hosted-runner-groups-for-org)
• POST /orgs/{org}/actions/runner-groups (actions/create-self-hosted-runner-group-for-org)
• GET /orgs/{org}/actions/runner-groups/{runner_group_id} (actions/get-self-hosted-runner-group-for-org)
• PATCH /orgs/{org}/actions/runner-groups/{runner_group_id} (actions/update-self-hosted-runner-group-for-org)
• GET /orgs/{org}/actions/runner-groups/{runner_group_id}/repositories (actions/list-repo-access-to-self-hosted-runner-group-in-org)
• GET /orgs/{org}/actions/runner-groups/{runner_group_id}/runners (actions/list-self-hosted-runners-in-group-for-org)
• GET /orgs/{org}/actions/runners (actions/list-self-hosted-runners-for-org)
• GET /orgs/{org}/actions/runners/downloads (actions/list-runner-applications-for-org)
• GET /orgs/{org}/actions/secrets (actions/list-org-secrets)
• GET /orgs/{org}/actions/secrets/{secret_name}/repositories (actions/list-selected-repos-for-org-secret)
• GET /repos/{owner}/{repo}/actions/artifacts (actions/list-artifacts-for-repo)
• GET /repos/{owner}/{repo}/actions/permissions (actions/get-github-actions-permissions-repository)
• GET /repos/{owner}/{repo}/actions/permissions/selected-actions (actions/get-allowed-actions-repository)
• GET /repos/{owner}/{repo}/actions/runners (actions/list-self-hosted-runners-for-repo)
• GET /repos/{owner}/{repo}/actions/runners/downloads (actions/list-runner-applications-for-repo)
• GET /repos/{owner}/{repo}/actions/runs (actions/list-workflow-runs-for-repo)
• GET /repos/{owner}/{repo}/actions/runs/{run_id}/artifacts (actions/list-workflow-run-artifacts)
• GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs (actions/list-jobs-for-workflow-run)
• GET /repos/{owner}/{repo}/actions/runs/{run_id}/timing (actions/get-workflow-run-usage)
• GET /repos/{owner}/{repo}/actions/secrets (actions/list-repo-secrets)
• GET /repos/{owner}/{repo}/actions/workflows (actions/list-repo-workflows)
• GET /repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs (actions/list-workflow-runs)
• GET /repos/{owner}/{repo}/actions/workflows/{workflow_id}/timing (actions/get-workflow-usage)

notifications

• GET /notifications (activity/list-notifications-for-authenticated-user)
• GET /notifications/threads/{thread_id} (activity/get-thread)

projects

• GET /orgs/{org}/teams/{team_slug}/projects (teams/list-projects-in-org)
• GET /orgs/{org}/teams/{team_slug}/projects/{project_id} (teams/check-permissions-for-project-in-org)
• POST /projects/columns/cards/{card_id}/moves (projects/move-card)
• POST /projects/columns/{column_id}/moves (projects/move-column)

git

• POST /repos/{owner}/{repo}/git/blobs (git/create-blob)
• POST /repos/{owner}/{repo}/git/commits (git/create-commit)
• GET /repos/{owner}/{repo}/git/commits/{commit_sha} (git/get-commit)
• GET /repos/{owner}/{repo}/git/matching-refs/{ref} (git/list-matching-refs)
• GET /repos/{owner}/{repo}/git/ref/{ref} (git/get-ref)
• POST /repos/{owner}/{repo}/git/refs (git/create-ref)
• PATCH /repos/{owner}/{repo}/git/refs/{ref} (git/update-ref)

enterprise

• GET /enterprises/{enterprise}/actions/permissions (enterprise-admin/get-github-actions-permissions-enterprise)
• GET /enterprises/{enterprise}/actions/permissions/organizations (enterprise-admin/list-selected-organizations-enabled-github-actions-enterprise)
• GET /enterprises/{enterprise}/actions/permissions/selected-actions (enterprise-admin/get-allowed-actions-enterprise)
• GET /enterprises/{enterprise}/actions/runner-groups (enterprise-admin/list-self-hosted-runner-groups-for-enterprise)
• POST /enterprises/{enterprise}/actions/runner-groups (enterprise-admin/create-self-hosted-runner-group-for-enterprise)
• GET /enterprises/{enterprise}/actions/runner-groups/{runner_group_id} (enterprise-admin/get-self-hosted-runner-group-for-enterprise)
• PATCH /enterprises/{enterprise}/actions/runner-groups/{runner_group_id} (enterprise-admin/update-self-hosted-runner-group-for-enterprise)
• GET /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/organizations (enterprise-admin/list-org-access-to-self-hosted-runner-group-in-enterprise)
• GET /enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners (enterprise-admin/list-self-hosted-runners-in-group-for-enterprise)
• GET /enterprises/{enterprise}/actions/runners (enterprise-admin/list-self-hosted-runners-for-enterprise)
• GET /enterprises/{enterprise}/actions/runners/downloads (enterprise-admin/list-runner-applications-for-enterprise)
• GET /enterprises/{enterprise}/settings/billing/actions (billing/get-github-actions-billing-ghe)
• GET /enterprises/{enterprise}/settings/billing/packages (billing/get-github-packages-billing-ghe)
• GET /enterprises/{enterprise}/settings/billing/shared-storage (billing/get-shared-storage-billing-ghe)
• GET /scim/v2/enterprises/{enterprise}/Groups (enterprise-admin/list-provisioned-groups-enterprise)
• POST /scim/v2/enterprises/{enterprise}/Groups (enterprise-admin/provision-and-invite-enterprise-group)
• GET /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id} (enterprise-admin/get-provisioning-information-for-enterprise-group)
• PUT /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id} (enterprise-admin/set-information-for-provisioned-enterprise-group)
• PATCH /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id} (enterprise-admin/update-attribute-for-enterprise-group)
• GET /scim/v2/enterprises/{enterprise}/Users (enterprise-admin/list-provisioned-identities-enterprise)
• POST /scim/v2/enterprises/{enterprise}/Users (enterprise-admin/provision-and-invite-enterprise-user)
• GET /scim/v2/enterprises/{enterprise}/Users/{scim_user_id} (enterprise-admin/get-provisioning-information-for-enterprise-user)
• PUT /scim/v2/enterprises/{enterprise}/Users/{scim_user_id} (enterprise-admin/set-information-for-provisioned-enterprise-user)
• PATCH /scim/v2/enterprises/{enterprise}/Users/{scim_user_id} (enterprise-admin/update-attribute-for-enterprise-user)

others

• GET /app/hook/config (apps/get-webhook-config-for-app)
• PATCH /app/hook/config (apps/update-webhook-config-for-app)
• GET /emojis (emojis/get)
• GET /orgs/{org}/hooks/{hook_id}/config (orgs/get-webhook-config-for-org)
• PATCH /orgs/{org}/hooks/{hook_id}/config (orgs/update-webhook-config-for-org)
• GET /orgs/{org}/invitations (orgs/list-pending-invitations)
• POST /orgs/{org}/invitations (orgs/create-invitation)
• GET /orgs/{org}/settings/billing/actions (billing/get-github-actions-billing-org)
• GET /orgs/{org}/settings/billing/packages (billing/get-github-packages-billing-org)
• GET /orgs/{org}/settings/billing/shared-storage (billing/get-shared-storage-billing-org)
• GET /orgs/{org}/team-sync/groups (teams/list-idp-groups-for-org)
• GET /orgs/{org}/teams/{team_slug}/invitations (teams/list-pending-invitations-in-org)
• GET /orgs/{org}/teams/{team_slug}/team-sync/group-mappings (teams/list-idp-groups-in-org)
• PATCH /orgs/{org}/teams/{team_slug}/team-sync/group-mappings (teams/create-or-update-idp-group-connections-in-org)
• GET /repos/{owner}/{repo}/code-scanning/alerts (code-scanning/list-alerts-for-repo)
• GET /repos/{owner}/{repo}/code-scanning/alerts/{alert_number} (code-scanning/get-alert)
• PATCH /repos/{owner}/{repo}/code-scanning/alerts/{alert_number} (code-scanning/update-alert)
• GET /repos/{owner}/{repo}/code-scanning/analyses (code-scanning/list-recent-analyses)
• GET /repos/{owner}/{repo}/commits/{commit_sha}/branches-where-head (repos/list-branches-for-head-commit)
• GET /repos/{owner}/{repo}/hooks/{hook_id}/config (repos/get-webhook-config-for-repo)
• PATCH /repos/{owner}/{repo}/hooks/{hook_id}/config (repos/update-webhook-config-for-repo)
• GET /repos/{owner}/{repo}/issues/{issue_number}/events (issues/list-events)
• GET /repos/{owner}/{repo}/issues/{issue_number}/timeline (issues/list-events-for-timeline)
• GET /repos/{owner}/{repo}/keys (repos/list-deploy-keys)
• POST /repos/{owner}/{repo}/keys (repos/create-deploy-key)
• GET /repos/{owner}/{repo}/keys/{key_id} (repos/get-deploy-key)
• GET /repos/{owner}/{repo}/languages (repos/list-languages)
• GET /repos/{owner}/{repo}/notifications (activity/list-repo-notifications-for-authenticated-user)
• GET /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers (pulls/list-requested-reviewers)
• GET /repos/{owner}/{repo}/stats/participation (repos/get-participation-stats)
• GET /repos/{owner}/{repo}/topics (repos/get-all-topics)
• PUT /repos/{owner}/{repo}/topics (repos/replace-all-topics)
• GET /teams/{team_id}/invitations (teams/list-pending-invitations-legacy)
• GET /teams/{team_id}/projects (teams/list-projects-legacy)
• GET /teams/{team_id}/projects/{project_id} (teams/check-permissions-for-project-legacy)
• GET /teams/{team_id}/team-sync/group-mappings (teams/list-idp-groups-for-legacy)
• PATCH /teams/{team_id}/team-sync/group-mappings (teams/create-or-update-idp-group-connections-legacy)
• GET /user/keys (users/list-public-ssh-keys-for-authenticated)
• POST /user/keys (users/create-public-ssh-key-for-authenticated)
• GET /user/keys/{key_id} (users/get-public-ssh-key-for-authenticated)
• GET /users/{username}/settings/billing/actions (billing/get-github-actions-billing-user)
• GET /users/{username}/settings/billing/packages (billing/get-github-packages-billing-user)
• GET /users/{username}/settings/billing/shared-storage (billing/get-shared-storage-billing-user)

[Schema Inaccuracy] components.schemas.code-scanning-alert-instances schema is correct

Schema Inaccuracy

A "type": "array" requires "items", which in turn can be of type "object" with the "properties" key

      "code-scanning-alert-instances": {
        "nullable": true,
        "type": "array",
        "properties": {
          "ref": {
            "$ref": "#/components/schemas/code-scanning-alert-ref"
          },
          "analysis_key": {
            "$ref": "#/components/schemas/code-scanning-analysis-analysis-key"
          },
          "environment": {
            "$ref": "#/components/schemas/code-scanning-alert-environment"
          },
          "matrix_vars": {
            "nullable": true,
            "type": "string"
          },
          "state": {
            "$ref": "#/components/schemas/code-scanning-alert-state"
          }
        }
      },

Expected

      "code-scanning-alert-instances": {
        "nullable": true,
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "ref": {
              "$ref": "#/components/schemas/code-scanning-alert-ref"
            },
            "analysis_key": {
              "$ref": "#/components/schemas/code-scanning-analysis-analysis-key"
            },
            "environment": {
              "$ref": "#/components/schemas/code-scanning-alert-environment"
            },
            "matrix_vars": {
              "nullable": true,
              "type": "string"
            },
            "state": {
              "$ref": "#/components/schemas/code-scanning-alert-state"
            }
          }
        }
      },

Reproduction Steps

n/a

notifications spam to security@

Please turn off email notifications for Hubot on this repo. It's spamming the security mailbox in Halp.

[Schema Inaccuracy] Object properties are mistakenly under an array schema

Schema Inaccuracy

Under the components object, at schemas/feed/properties/_links, the _links schema is of type array but it contains a required properties array. Upon inspection, it appears the required array should just be nested one level deeper inside the _links/items property which is indeed an object and does indeed have properties corresponding to the entries in the required array.

Expected

    ...
        _links:
          type: array
          items:
            type: object
            required: # <- the bit that is incorrectly specified directly under `_links` currently.
            - timeline
            - user
            properties:
              timeline:
                type: object
                properties:
                  href:
                    type: string
                  type:
                    type: string
              user:
                type: object
                properties:
                  href:
                    type: string
                  type:
                    type: string
    ...

[Schema Inaccuracy] Commit SHA and URL are nullable

Schema Inaccuracy

In api.github.com.json, lines 57297- 57312, I can see this:

{
  /*...*/
  "commit": {
    "title": "Commit",
    "description": "Commit",
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "format": "uri",
        "example": "https://api.github.com/repos/octocat/Hello-World/commits/6dcb09b5b57875f334f61aebed695e2e4193db5e",
        "nullable": true /* <<<=== */
      },
      "sha": {
        "type": "string",
        "example": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
        "nullable": true /* <<<=== */
      }
      /*...*/
    }
    /*...*/
  }
  /*...*/
}

Which later results in:

commit: {
  url: string | null;
  sha: string | null;
  //...
}

So, my code:

const branchData = await octokit.repos.getBranch({
  owner,
  repo,
  branch,
});

const sha: string = branchData.data.commit.sha;

Fails to compile with the error:

Type 'string | null' is not assignable to type 'string'.
  Type 'null' is not assignable to type 'string'.ts(2322)

Expected

url and sha properties on commit schema should be of type string instead of string | null

Reproduction Steps

N/A (or see my code example above)

[Schema Inaccuracy] Type of author_association is not an enum

Schema Inaccuracy

The following components have an author_association property with a type of string:

• issue-simple
• issue-comment
• gist-comment
• issue
• commit-comment
• pull-request-simple
• issue-event
• issue-event-for-issue
• pull-request
• pull-request-review-comment
• pull-request-review
• review-comment
• issue-search-result-item

Expected

The type of the author_association property should be an enum, similar to the CommentAuthorAssociation enum defined in the GraphQL API, with the following values:

• COLLABORATOR
• CONTRIBUTOR
• FIRST_TIMER
• FIRST_TIME_CONTRIBUTOR
• MANNEQUIN
• MEMBER
• NONE
• OWNER

Reproduction Steps

N/A

[Schema Inaccuracy] Servers option only documents the API can be accessed over HTTP with no sensible default

Schema Inaccuracy

This issue is related to the default and only server that is described in the document:

/servers/0/url
/servers/0/variables/hostname/default

servers:
- url: http://{hostname}
  variables:
    hostname:
      description: Self-hosted Enterprise Server or Enterprise Cloud hostname
      default: HOSTNAME

The two issues are:

1. The server makes use of variables, however the described API only permits users to access the github API over HTTP and not (i presume) the recommended HTTPS protocol. The hostname itself is the only portion that the user is permitted to substitute. I could be wrong here.
2. There's no sensible default provided, namely https://github.com. From the description, it seems like the API is only describing access to self-hosted enterprise servers and not the public github instance.

These are both issues mainly when generating an SDK from the OpenAPI doc. It requires manual user input to provide the github hostname, and even then is on the incorrect protocol. We can do better 👍

Expected

I expected github.com to be documented as the default server
I expected the OAS doc to describe access to a github deployment over https

This could be done in a couple of different ways which make little difference overall:

First, ensure that the protocol is flexible, either as a parameterised variable {protocol}://{hostname}, making the entire URL a configurable variable {url}, or add a second server with https://{hostname}

Second, setting github.com as the default server could be done either as the first server in the list:

servers:
- url: https://github.com
  description: Public GitHub server
- url: {url}
  description: Self-hosted Enterprise Server or Enterprise Cloud
  variables:
    url:
      description: Self-hosted Enterprise Server or Enterprise Cloud URL
      default: https://hostname

or setting the default value of the URL variable:

servers:
- url: {url}
  variables:
    url:
      default: https://github.com

Reproduction Steps

go to https://petstore.swagger.io/ and paste in https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/ghes-2.21/ghes-2.21.yaml

Have to manually configure server with github.com.

Note: the API does work over http after testing. You can ignore that part, or include https anyway if people prefer to access the github API that way without any redirects.

[Schema Inaccuracy] Move comfort-fade preview out of description

Schema Inaccuracy

Expected

The List review comments on a pull request operation has content specific to the comfort-fade preview. We should ensure that the content applies to any operations that include the comfort-fade preview and then integrate the content directly into the preview markdown.

• operation file: https://github.com/github/openapi/blob/master/definitions/operations/pulls/list-review-comments.yml

We'll also want to ✂️ the last sentence:

The reactions key will have the following payload where url can be used to construct the API location for listing and creating reactions.

Other instances that are similar:

• https://help.github.com/en/rest/reference/pulls#list-review-comments-in-a-repository
• https://help.github.com/en/rest/reference/pulls#get-a-review-comment-for-a-pull-request
• https://help.github.com/en/rest/reference/pulls#create-a-review-comment-for-a-pull-request
• https://help.github.com/en/rest/reference/pulls#update-a-review-comment-for-a-pull-request

[Schema Inaccuracy] license / termsOfService urls

Schema Inaccuracy

In the info section, the license.url property is pointing to GitHub's TOS, when it should be a link to a copy of the MIT license itself. There is an info.termsOfService property for this purpose.

Expected

openapi: 3.0.3
info:
  version: 0.0.3
  title: GitHub v3 REST API
  description: GitHub's v3 REST API.
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT.html
  termsOfService: https://help.github.com/articles/github-terms-of-service/
  contact:
    name: Support
    url: https://support.github.com

Reproduction Steps

n/a

[Schema Inaccuracy] Add preview notes to Blocking Users API

Schema Inaccuracy

Originally reported by @runleonarun. https://github.com/github/openapi/issues/215

Expected

The Blocking Users API is under preview, but there are no preview notes showing up on help-docs. We need to test to make sure all endpoints are under preview but I believe they are as our convention used to be to put the note at the top of the page when all endpoints are under preview.

Compare https://developer.github.com/v3/users/blocking/ and https://help.github.com/en/rest/reference/users#blocking-users

Missing enum values on check-run / check-suites properties

check-run

{
          "status": {
            "description": "The phase of the lifecycle that the check is currently in.",
            "example": "queued",
            "type": "string",
            "enum": [
              "queued",
              "in_progress",
              "completed"
            ]
          },
          "conclusion": {
            "type": "string",
            "example": "neutral",
            "nullable": true
          }
}

The check run Status has the correct enums defined but the conclusion property is missing a list of possible values. The actual list of possible values is provided in the documentation

Check suites

{
"status": {
            "type": "string",
            "example": "completed",
            "nullable": true
          },
          "conclusion": {
            "type": "string",
            "example": "neutral",
            "nullable": true
          },
}

The same is also the case for the "status" and "conclusion" for check suites

[Schema Inaccuracy] operationIds for "/user/interaction-limits" operations are inconsistent with other operationIds

Schema Inaccuracy

Excerpt

{
  "/user/interaction-limits": {
    "get": {
      "operationId": "interactions/get-restrictions-for-your-public-repos"
    },
    "put": {
      "operationId": "interactions/set-restrictions-for-your-public-repos"
    },
    "delete": {
      "operationId": "interactions/remove-restrictions-for-your-public-repos"
    }
  }
}

Instead of "your", all other /user/* endpoints use "for-authenticated-user".

Expected

{
  "/user/interaction-limits": {
    "get": {
      "operationId": "interactions/get-public-repo-restrictions-for-authenticated-user"
    },
    "put": {
      "operationId": "interactions/set-public-repo-restrictions-for-authenticated-user"
    },
    "delete": {
      "operationId": "interactions/remove-public-repo-restrictions-for-authenticated-user"
    }
  }
}

Reproduction Steps

n/a

[Schema Inaccuracy] `components/schemas/installation-token` is missing `"required"` key

The #/components/schemas/installation-token reference is only used in the apps/create-installation-access-token operation.

Schema Inaccuracy

      "installation-token": {
        "title": "Installation Token",
        "description": "Authentication token for a GitHub App installed on a user or org.",
        "type": "object",
        "properties": {
          "token": { "type": "string" },
          "expires_at": { "type": "string" },
          "permissions": {
            "type": "object",
            "properties": {
              "issues": { "type": "string" },
              "contents": { "type": "string" },
              "metadata": { "type": "string", "example": "read" },
              "single_file": { "type": "string", "example": "read" }
            }
          },
          "repository_selection": {
            "type": "string",
            "enum": ["all", "selected"]
          },
          "repositories": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/repository" }
          },
          "single_file": { "type": "string", "example": "README.md" },
          "has_multiple_single_files": { "type": "boolean", "example": true },
          "single_file_paths": {
            "type": "array",
            "items": {
              "type": "string",
              "example": ["config.yml", ".github/issue_TEMPLATE.md"]
            }
          }
        }
      },

Expected

      "installation-token": {
        "title": "Installation Token",
        "description": "Authentication token for a GitHub App installed on a user or org.",
        "type": "object",
        "properties": {
          "token": { "type": "string" },
          "expires_at": { "type": "string" },
          "permissions": {
            "type": "object",
            "properties": {
              "issues": { "type": "string" },
              "contents": { "type": "string" },
              "metadata": { "type": "string", "example": "read" },
              "single_file": { "type": "string", "example": "read" }
            }
          },
          "repository_selection": {
            "type": "string",
            "enum": ["all", "selected"]
          },
          "repositories": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/repository" }
          },
          "single_file": { "type": "string", "example": "README.md" },
          "has_multiple_single_files": { "type": "boolean", "example": true },
          "single_file_paths": {
            "type": "array",
            "items": {
              "type": "string",
              "example": ["config.yml", ".github/issue_TEMPLATE.md"]
            }
          }
        },
        "required": [
          "token",
          "expires_at",
          "permissions",
          "repository_selection"
        ]
      },

Reproduction Steps

https://runkit.com/gr2m/github-rest-api-description-106

[Schema Inaccuracy] security object mixes function with state

Schema Inaccuracy

The request/response for the API call are at a minimum, only concerned with ROLES/Privileges associated with an endpoint... not with the OAuth handshake. That is all function handled on the backend.

{
"type": "oauth2",
"flows": {
"implicit": {
"authorizationUrl": "https://example.com/api/oauth/dialog",
"scopes": {
"write:pets": "modify pets in your account",
"read:pets": "read your pets"
}
}
}
}

This function can be defined (and usually is) in separate more secure documents that don't have to be syncronized and/or cached. Also this data is single use wheras the other data in the document is shared.

Expected

Security is better handled by associating ROLES with endpoints so that once token is issued, a check can be easily made against stated ROLES associated with endpoints

ex.
"REQUEST": {
"permitAll":["firstName","username","lastName","email"],
"ROLE_ADMIN":["enabled","password","id","version"]
},
"RESPONSE": {
"permitAll":["email"],
"ROLE_ADMIN":["id","version"]
}

Above shows how ROLE_ADMIN would get a concatenated dataset of 'permitAll' plus their own privilege.

This keeps the schema related ONLY to the request/response call flow.

Reproduction Steps

ex
curl -v -H "Content-Type: application/json" -H "Authorization: Bearer a7ectf7qgulb38bu22l136r7cf0qv12j" --request GET "http://localhost:8080/v1.6.58/person/show/225"

[Schema Inaccuracy] Typo in docs

Schema Inaccuracy

Typo whick instead of which on line 26253 of the ghes-2.22.yaml

[Schema Inaccuracy] Rename `schemas.integration` to `schemas.app`

Schema Inaccuracy

Not an inaccuracy per se, but for the sake of consistency, it would be great if schemas.integration could be renamed to schemas.app. I'm in the process of migrating the Octokit SDKs to be generated from the official OpenAPI spec, and these internal naming will be reflected in TypeScript types.

If I recall correctly, GitHub Apps were called integrations when launched?

[Schema Inaccuracy] Incomplete parameter table "update an import"

Schema Inaccuracy

Originally reported by @martin389. https://github.com/github/openapi/issues/283

On the developer site, Update an import has subsections for parameters:

• Parameters for updating project choice (old docs)
• Parameters for restarting import (old docs)

These need to be added to the parameter table of the help-docs Update an import.