[Tracking issue] Generating client code from the OpenAPI schema

[indigok]

Opening this to track the progress of generating the client code from the OpenAPI spec in the shared routes directory.

👀 #1010 for proof of concept
👀 octokit/routes#168 for more context

[zeke]

Wow! So cool to see this happening.

cc @sarahs @jleaver

[indigok]

Octokit.rb has a stable release of v4 on the branch 4-stable. These PRs will now be merged into master as we build up v5 🚀

[indigok]

With the current naming schema, we’ve generated 33/91 clients. Thus, as we’ve reached a third of the way through the project and finally have several moving parts solidified, I’m going to take a moment to write some documentation.

Steps to generate a new client

0. Have both octokit/routes and octokit/octokit.rb in the same directory. Everything else will be run from inside of octokit.rb
1. Add the client you want to generate to the supported resources. The client names mirror the documentation url after v3, i.e. pull request comments go from https://developer.github.com/v3/pulls/comments/ to pulls_comments.
2. Run bundle exec rake generate
 to generate all the clients listed in the above line from the openapi spec.
3. Compare the diff and see if the generated client has any mistakes. The old clients will likely be in a different file but try to find all the corresponding methods - checking the documentation link is a good way to ensure you're finding the right ones. The clients don’t have to be an exact match but should be understandable and useable.
4. Change anything you need to in openapi_client_generator. A high risk area is the namespace method. As the API becomes more standardized, hopefully we can reassess this method but as it stands, it’s one of the hardest parts to generate and there’s a lot of special casing. binding.pry is your friend.
5. Regenerate and tweak the generator as needed until you feel comfortable pushing and merging it 🚀

Tests

The new way of testing is outlined in #1258. Ideally, if you’re working on a client that contains one of these scenarios, go ahead and add the matching test.

Openapi schema

This generator is currently being pulled from octokit/routes which scrapes the developer docs. In the near future, the new source of truth will be openapi and we’ll need to make the switch. The main change appears to be switching from a JSON to a YAML schema, but most of the fields are the same.

Additionally, useful parts to understand in the openapi structure, as referenced in octokit/routes, are the index file which shows the paths under operations to each endpoint. These two areas help provide you with all the information you have to generate the SDK.

[zeke]

Thanks for the update @hmharvey 👍

In the near future, the new source of truth will be openapi and we’ll need to make the switch. The main change appears to be switching from a JSON to a YAML schema, but most of the fields are the same.

FYI the built definitions files are still JSON. See https://unpkg.com/browse/@github/[email protected]/dist/

[indigok]

FYI the built definitions files are still JSON. See https://unpkg.com/browse/@github/[email protected]/dist/

Aha so they are! Thanks pointing that out 🙇🏻‍♀️

[maxandersen]

tried follow the instructions in "#1157 (comment)" but I get:

 bundle exec rake generate
rake aborted!
Don't know how to build task 'generate' (See the list of available tasks with `rake --tasks`)

nor can I find languages mentioned in https://github.com/octokit/octokit.rb/blob/master/lib/openapi_client_generator.rb?rgh-link-date=2020-05-26T23%3A17%3A40Z#L408

was this removed / moved ?

[github-actions]

👋 Hey Friends, this issue has been automatically marked as stale because it has no recent activity. It will be closed if no further activity occurs. Please add the Status: Pinned label if you feel that this issue needs to remain open/active. Thank you for your contributions and help in keeping things tidy!