Code generation - what are our options?

[JonruAlveus]

We’re talking a lot about code gen and I thought it would be good to kick off a chat about it.

So far I’ve successfully generated a postman collection (not really related to this Repo but it was pretty easy). I also unsuccessfully generated a c# client using the ms open api connected service. There is one endpoint with one enum that accepted add, Add, remove, Remove etc. which exploded because you ended up with two enums with the same name, but different values. Doh. So I guess we could ask to change the documentation to only show upper or lower or we find a different tool.

Another thing to consider is extending the generated code with the undocumented endpoints (repos/owner/name is there but repos/id or repository/id aren’t).

Other options could be handlebars or liquid templates to build own own entirely or there must be others out there. I guess we could also consider doctoring the open api json ourselves to make it fit to our need?

[JamieMagee]

I think a Roslyn source generator¹ would be the best way to build the client. The only one I know of is H.NSwag.Generator²

Footnotes

1. https://docs.microsoft.com/en-us/dotnet/csharp/roslyn-sdk/source-generators-overview ↩

2. https://github.com/HavenDV/H.NSwag.Generator ↩

[HavenDV]

Thanks for pointing out my repository. In fact, my generator just uses the libraries provided by https://github.com/RicoSuter/NSwag/ and wraps it up in a way that is easy to use. But I see a lot of shortcomings in this generation, and there is a lot of room for development.

[nickfloyd]

I think a good start is to ask what our overall goals are with generation are...

Generation...

Immediate needs:

• SHOULD be able to use things like the OpenAPI descriptions and GraphQL schema endpoints to generate models and APIs
• SHOULD support the goal of having all SDK models (request and response) synchronized with the current REST API surface
• SHOULD support the generation of API methods as well as models (if needed)
• SHOULD support the ability to package all models and source them as an external library (optional initially but a great future opportunity)
• SHOULD have validators to verify integrity and correctness
• SHOULD be as automated as possible - potentially having actions generate and issue a PR when changes are detected in the OpenAPI descriptions

Future needs:

• NEEDS to support across language generation - the ideal would be that we point the generator at a language specification (or static template) and the OpenAPI definitions, and it spits out static files that can be packaged and distributed
• SHOULD use language definitions. specifications, and things like RFCs to help in the generation of the code so that future iterations of the language are supported
• SHOULD support API, workflow, and model interpolation - so workflows can be defined in templates and generated dynamically.

Optional considerations/questions:

• Should generation be wholesale or incremental?
• Should generation be sophisticated enough to support detecting breaking changes?
• What parts of the SDK should be generated and what parts shouldn't be? Models, APIs, helpers...

[JonruAlveus]

I'd like to add another one:

• SHOULD be extendible to cover situations where routes etc. are not in the openapi spec, but still work.

I'd be pro automating as much as possible with daily builds etc. Would we need to support multiple versions of the openapi spec, for GHE instances? I wonder if there's layers to this process like:

• OpenApi/GraphQL(/WebHooks?) spec repos
• Generated SDK and API methods (many languages)
• Generated workflows repors (many languages)

Optionals:

• I would go for wholesale, incremental could become painful to maintain when things are obsoleted?
• If it can, it would certainly help users to know when there are breaking changes. Even if all it does is increment the major release number?
• Everything! :D And if possible, that could include the authentication side. That's pretty complex and there's a few ways to do things, so making it so that can be generated out into multiple languages would be very cool.

[JonruAlveus]

Here's some stats on where we are vs the api spec (pr here)

Caveats - this is the number of routes, not the number of endpoints ie "/app" could actually be represented as a GET, PUT, POST, DELETE etc. so there could be many more that aren't represented here.

This does beg the question - how close do we have to get before we switch to generated code? Could we generate the models to start with and replace the ones we have at the moment?

Number of SDK routes: 328
Number of OpenApi routes: 564

Matches: 198
/app
/app/installations
/app/installations/{0}
/apps/{0}
/emojis
/events
/feeds
/gists
/gists/public
/gists/starred
/gists/{0}
/gists/{0}/comments
/gists/{0}/comments/{1}
/gists/{0}/commits
/gists/{0}/forks
/gists/{0}/star
/gitignore/templates
/gitignore/templates/{0}
/installation/repositories
/licenses
/licenses/{0}
/markdown
/markdown/raw
/meta
/networks/{0}/{1}/events
/notifications/threads/{0}
/notifications/threads/{0}/subscription
/organizations
/orgs/{0}
/orgs/{0}/events
/orgs/{0}/hooks
/orgs/{0}/hooks/{1}
/orgs/{0}/hooks/{1}/pings
/orgs/{0}/installation
/orgs/{0}/invitations
/orgs/{0}/issues
/orgs/{0}/members
/orgs/{0}/members/{1}
/orgs/{0}/memberships/{1}
/orgs/{0}/migrations
/orgs/{0}/migrations/{1}
/orgs/{0}/migrations/{1}/archive
/orgs/{0}/migrations/{1}/repos/{2}/lock
/orgs/{0}/projects
/orgs/{0}/repos
/orgs/{0}/teams
/projects/columns/cards/{0}
/projects/columns/cards/{0}/moves
/projects/columns/{0}
/projects/columns/{0}/cards
/projects/columns/{0}/moves
/projects/{0}
/projects/{0}/columns
/repos/{0}/{1}
/repos/{0}/{1}/assignees
/repos/{0}/{1}/assignees/{2}
/repos/{0}/{1}/branches
/repos/{0}/{1}/branches/{2}
/repos/{0}/{1}/branches/{2}/protection
/repos/{0}/{1}/branches/{2}/protection/restrictions
/repos/{0}/{1}/branches/{2}/protection/restrictions/teams
/repos/{0}/{1}/branches/{2}/protection/restrictions/users
/repos/{0}/{1}/codeowners/errors
/repos/{0}/{1}/collaborators
/repos/{0}/{1}/collaborators/{2}
/repos/{0}/{1}/collaborators/{2}/permission
/repos/{0}/{1}/comments
/repos/{0}/{1}/comments/{2}
/repos/{0}/{1}/comments/{2}/reactions
/repos/{0}/{1}/comments/{2}/reactions/{3}
/repos/{0}/{1}/commits
/repos/{0}/{1}/commits/{2}/comments
/repos/{0}/{1}/commits/{2}
/repos/{0}/{1}/commits/{2}/status
/repos/{0}/{1}/commits/{2}/statuses
/repos/{0}/{1}/contents/{2}
/repos/{0}/{1}/contributors
/repos/{0}/{1}/deployments
/repos/{0}/{1}/deployments/{2}/statuses
/repos/{0}/{1}/events
/repos/{0}/{1}/forks
/repos/{0}/{1}/git/commits
/repos/{0}/{1}/git/commits/{2}
/repos/{0}/{1}/git/refs
/repos/{0}/{1}/git/refs/{2}
/repos/{0}/{1}/git/tags
/repos/{0}/{1}/git/tags/{2}
/repos/{0}/{1}/git/trees
/repos/{0}/{1}/git/trees/{2}
/repos/{0}/{1}/hooks
/repos/{0}/{1}/hooks/{2}
/repos/{0}/{1}/hooks/{2}/pings
/repos/{0}/{1}/hooks/{2}/tests
/repos/{0}/{1}/installation
/repos/{0}/{1}/issues
/repos/{0}/{1}/issues/comments
/repos/{0}/{1}/issues/comments/{2}
/repos/{0}/{1}/issues/comments/{2}/reactions
/repos/{0}/{1}/issues/comments/{2}/reactions/{3}
/repos/{0}/{1}/issues/events
/repos/{0}/{1}/issues/events/{2}
/repos/{0}/{1}/issues/{2}
/repos/{0}/{1}/issues/{2}/assignees
/repos/{0}/{1}/issues/{2}/comments
/repos/{0}/{1}/issues/{2}/events
/repos/{0}/{1}/issues/{2}/labels
/repos/{0}/{1}/issues/{2}/labels/{3}
/repos/{0}/{1}/issues/{2}/lock
/repos/{0}/{1}/issues/{2}/reactions
/repos/{0}/{1}/issues/{2}/reactions/{3}
/repos/{0}/{1}/issues/{2}/timeline
/repos/{0}/{1}/keys
/repos/{0}/{1}/keys/{2}
/repos/{0}/{1}/labels
/repos/{0}/{1}/labels/{2}
/repos/{0}/{1}/languages
/repos/{0}/{1}/license
/repos/{0}/{1}/merges
/repos/{0}/{1}/milestones
/repos/{0}/{1}/milestones/{2}
/repos/{0}/{1}/milestones/{2}/labels
/repos/{0}/{1}/notifications
/repos/{0}/{1}/pages
/repos/{0}/{1}/pages/builds
/repos/{0}/{1}/pages/builds/latest
/repos/{0}/{1}/projects
/repos/{0}/{1}/pulls
/repos/{0}/{1}/pulls/comments
/repos/{0}/{1}/pulls/comments/{2}
/repos/{0}/{1}/pulls/comments/{2}/reactions
/repos/{0}/{1}/pulls/comments/{2}/reactions/{3}
/repos/{0}/{1}/pulls/{2}
/repos/{0}/{1}/pulls/{2}/comments
/repos/{0}/{1}/pulls/{2}/commits
/repos/{0}/{1}/pulls/{2}/files
/repos/{0}/{1}/pulls/{2}/merge
/repos/{0}/{1}/pulls/{2}/reviews
/repos/{0}/{1}/pulls/{2}/reviews/{3}
/repos/{0}/{1}/pulls/{2}/reviews/{3}/comments
/repos/{0}/{1}/pulls/{2}/reviews/{3}/dismissals
/repos/{0}/{1}/pulls/{2}/reviews/{3}/events
/repos/{0}/{1}/readme
/repos/{0}/{1}/releases
/repos/{0}/{1}/releases/assets/{2}
/repos/{0}/{1}/releases/latest
/repos/{0}/{1}/releases/tags/{2}
/repos/{0}/{1}/releases/{2}
/repos/{0}/{1}/releases/{2}/assets
/repos/{0}/{1}/stargazers
/repos/{0}/{1}/stats/contributors
/repos/{0}/{1}/stats/participation
/repos/{0}/{1}/statuses/{2}
/repos/{0}/{1}/subscribers
/repos/{0}/{1}/subscription
/repos/{0}/{1}/tags
/repos/{0}/{1}/teams
/repos/{0}/{1}/topics
/repos/{0}/{1}/traffic/clones
/repos/{0}/{1}/traffic/popular/paths
/repos/{0}/{1}/traffic/popular/referrers
/repos/{0}/{1}/traffic/views
/repos/{0}/{1}/transfer
/repos/{0}/{1}/generate
/repositories
/search/code
/search/issues
/search/labels
/search/repositories
/search/users
/teams/{0}
/teams/{0}/invitations
/teams/{0}/members
/teams/{0}/memberships/{1}
/teams/{0}/repos
/teams/{0}/repos/{1}/{2}
/teams/{0}/teams
/user/followers
/user/following
/user/following/{0}
/user/installations
/user/installations/{0}/repositories
/user/keys
/user/keys/{0}
/user/orgs
/user/starred/{0}/{1}
/user/teams
/users/{0}
/users/{0}/events/orgs/{1}
/users/{0}/followers
/users/{0}/following
/users/{0}/following/{1}
/users/{0}/gists
/users/{0}/installation
/users/{0}/keys
/users/{0}/orgs
/users/{0}/repos
/users/{0}/starred
/users/{0}/subscriptions