Skip to content

Use metadata to reconcile go-github with GitHub's OpenAPI descriptions#2919

Merged
gmlewis merged 38 commits intogoogle:masterfrom
WillAbides:meta4
Nov 3, 2023
Merged

Use metadata to reconcile go-github with GitHub's OpenAPI descriptions#2919
gmlewis merged 38 commits intogoogle:masterfrom
WillAbides:meta4

Conversation

@WillAbides
Copy link
Copy Markdown
Contributor

@WillAbides WillAbides commented Sep 9, 2023

see #2908

TODO before submitting for review:

  • Fix line-end issue on Windows
  • Update CONTRIBUTING.md
  • Add copyright notices to new files

This PR introduces a file called openapi_operations.yaml that contains details of GitHub's endpoints as described in https://github.com/github/rest-api-description. When combined with the //meta:operation directive, this allows us to automatically keep documentation links up to date, but more importantly it allows us to track endpoints as they are added and removed.

The change set is huge, but it is primarily made up of openapi_operations.yaml itself and changes to godoc.

"tools/cmd/metadata" is a tool to manage metadata.yaml. I'll paste its help output here for convenience:

Usage: metadata <command>

Flags:
  -h, --help               Show context-sensitive help.
  -C, --working-dir="."    Working directory. Should be the root of the go-github repository.

Commands:
  update-openapi
    Update openapi_operations.yaml from OpenAPI descriptions in github.com/github/rest-api-description at the given git ref.

  update-go
    Update go source code to be consistent with openapi_operations.yaml.
      - Adds and updates "// GitHub API docs:" comments for service methods.
      - Updates "//meta:operation" comments to use canonical operation names.
      - Updates formatting of "//meta:operation" comments to make sure there isn't a space between the "//" and the "meta".
      - Formats modified files with the equivalent of "go fmt".

  format
    Format whitespace in openapi_operations.yaml and sort its operations.

  unused
    List operations in openapi_operations.yaml that aren't used by any service methods.

Run "metadata <command> --help" for more information on a command.

I'm trying to limit the scope of this PR because its line count is already pretty high. I will make a follow-up PR with a daily scheduled workflow that runs "update-openapi" and "update-go" and creates a PR if there are changes.

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants