Contributing to and maintaining this repo could be helped by a metadata file for all of the endpoints go-github supports. It would map to GitHub's OpenAPI descriptions. In this proposal I'll call it operations.yaml.
An operations.yaml entry might look like:
- operation_id: pulls/request-reviewers
openapi:
method: POST
endpoint_url: '/repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers'
documentation_url: 'https://docs.github.com/rest/pulls/review-requests#request-reviewers-for-a-pull-request'
summary: Request reviewers for a pull request
go_method: PullRequestsService.RequestReviewersoperations.yaml could be updated by a scheduled GitHub action that opens a PR when it finds a change.
Initially operations.yaml would be useful for update-urls. Instead of having to resolve every documentation url, it could use the value stored in operations.yaml. update-urls could be expanded to also update godoc with the summary field.
It would also be useful for finding new endpoints for go-github to support. Eventually we could write a generator that uses operations.yaml to generate the boilerplate to implement new endpoints.
Overrides
There are probably endpoints where we don't want to use the OpenAPI data or maybe some that aren't even in the OpenAPI description. For those cases we can create an override section:
- operation_id: pulls/request-reviewers
openapi:
method: POST
endpoint_url: '/repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers'
documentation_url: 'https://docs.github.com/rest/pulls/review-requests#request-reviewers-for-a-pull-request'
summary: Request reviewers for a pull request
override:
documentation_url: https://some/other/url
go_method: PullRequestsService.RequestReviewersFor an endpoint that doesn't exist in the OpenAPI description, we create an entry with no openapi section and all required fields set in override. Here's a fictional PUT endpoint for the same url as above.
- operation_id: pulls/update-request-reviewers # manually created
override:
method: PUT
endpoint_url: '/repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers'
documentation_url: 'https://docs.github.com/rest/pulls/review-requestss#update-reviewers-for-a-pull-request'
summary: Update reviewers for a pull request
go_method: PullRequestsService.UpdateRequestReviewersMultiple OpenAPI Descriptions
So far I've been talking about "the" OpenAPI description, but there are several docs published:
- one for api.github.com
- one for api.github.com with a GitHub Enterprise subscription
- one for each version of GitHub Enterprise Server released since v2.18
- one for github.ae
We will need a way to reconcile these. Knowing how GitHub generates these, I doubt there will be any significant differences between versions for the same operation_id. However they will have different documentation URLs. We can reconcile which one to use by taking the first one where the operation_id exists in this order: api.github.com -> ghec -> ghes versions in descending order -> maybe github.ae if anybody ever asks for it.
Contributing to and maintaining this repo could be helped by a metadata file for all of the endpoints go-github supports. It would map to GitHub's OpenAPI descriptions. In this proposal I'll call it
operations.yaml.An
operations.yamlentry might look like:operations.yamlcould be updated by a scheduled GitHub action that opens a PR when it finds a change.Initially
operations.yamlwould be useful forupdate-urls. Instead of having to resolve every documentation url, it could use the value stored inoperations.yaml.update-urlscould be expanded to also update godoc with the summary field.It would also be useful for finding new endpoints for go-github to support. Eventually we could write a generator that uses
operations.yamlto generate the boilerplate to implement new endpoints.Overrides
There are probably endpoints where we don't want to use the OpenAPI data or maybe some that aren't even in the OpenAPI description. For those cases we can create an
overridesection:For an endpoint that doesn't exist in the OpenAPI description, we create an entry with no
openapisection and all required fields set inoverride. Here's a fictional PUT endpoint for the same url as above.Multiple OpenAPI Descriptions
So far I've been talking about "the" OpenAPI description, but there are several docs published:
We will need a way to reconcile these. Knowing how GitHub generates these, I doubt there will be any significant differences between versions for the same
operation_id. However they will have different documentation URLs. We can reconcile which one to use by taking the first one where theoperation_idexists in this order: api.github.com -> ghec -> ghes versions in descending order -> maybe github.ae if anybody ever asks for it.