Creating code samples from OpenAPI schema data

[zeke]

In #168, a new OpenAPI schema landed in this project, and will pave the way for a future where all the octokits have a shared schema! ❤️

Today I was inspecting the contents of the openapi/api.github.com/operations directory, and noticed that operationId values are all in snake-case format:

"operationId": "pulls-create-comment-reply"

It looks like these values are currently created by joining the scope and the endpoint.idName with a hyphen:

routes/lib/openapi.js

Line 193 in 261c763

operationId: [scope, endpoint.idName].join('-'),

I also noticed that there's already some code in this project for creating example code with toShellExample and toJsExample:

routes/lib/openapi.js

Line 261 in 261c763

function toJsExample ({ scope, endpoint, baseUrl }) {

)

This leads me to a few questions:

• Do the generated code examples work yet? Based on the current implementation of toJsExample my guess is no:

routes/lib/openapi.js

Line 269 in 261c763

return `octokit.${scope}.get(${Object.keys(params).length ? stringify(params, null, 2) : ''})`

• Can we switch to using operationId values that more closely match the method names octokit clients will use? For example, I'd suggest that pulls-create-comment-reply should instead be pulls.createCommentReply

I'm happy to help out on this, but wanted to open this issue first to discuss and get a sense of where things are with this effort before jumping to an implementation.

cc @gr2m @d11n

[gr2m]

operationId is language agnostic, I thought hyphens would be the easiest to work with. The respective language can then turn it into what ever feels native, such as camelCase for JavaScript.

I had to prefix operationId with the scope because operationIds need to be globally unique. Without the scope prefix there would be conflicts

The code examples work for JS should work, you can see it rendered at https://octokit-routes-openapi.now.sh.

The challenge with that approach is that all SDKs need to have the new endpoints implemented before the REST API docs gets published. And even then it would be helpful to know which version of the SDK introduced the new method.

Maybe the code examples should live in the repositories of the respective SDKs and then be pulled in from there into the central developer docs?

[d11n]

yeah...and in ruby, for example, PascalCase is used for modules/classes and snake_case for methods...so pulls.createCommentReply in octokit.rb would actually be:

Octokit::Client::Pulls.create_comment_reply

although currently it's actually:

Octokit::Client::PullRequests.create_pull_request_comment_reply
Octokit::Client::PullRequests.create_pull_reply   #alias
Octokit::Client::PullRequests.create_review_reply #alias

for reference, the current non-octokit/routes-powered octokit.rb: https://github.com/octokit/octokit.rb/blob/master/lib/octokit/client/pull_requests.rb#L218-L236

[d11n]

and i like the idea of sdk maintainers being responsible for the code that generates the examples...but perhaps it stays in this repo like:

./lib/endpoint/code-samples/curl.shell.js
                            gh3.js.js
                            github.js.js
                            github-client.coffee.js
                            octokit.net.js
                            octokit.rb.js
                            octokit-rest.js.js
                            octonode.js.js
                            ...

and the function signatures could be something like:

function toExample ({ route, scope, baseUrl }) {
  // insert unholy js written by non-jsers ;P
  return {
    sdk: {
      name,
      url,
      ...
    },
    infoString, // code fence info string
    // ^ https://github.github.com/gfm/#example-112
    //   https://github.com/github/linguist/blob/master/vendor/README.md
    codeString
  }
}

[zeke]

The code examples work for JS should work

It looks like they're all currently rendering as octokit.{scope}.get)(...). Here's an example:

---

operationId is language agnostic, I thought hyphens would be the easiest to work with. The respective language can then turn it into what ever feels native, such as camelCase for JavaScript.

Are scopes always a single word? If so, I suppose it's easy enough to assemble a method by extracting the first part before the hyphen. My suggestion is not about a specific capitalization preference, but more a clear way to differentiate the scope from the function name. I feel it's easier to derive Pulls.create_comment_reply from pulls.createCommentReply because you have a . separating the two.

[gr2m]

It looks like they're all currently rendering as octokit.{scope}.get)(...)

Ooopsiedooopsie

Are scopes always a single word

Not quite, there is oauth_authorizations for example.

My suggestion is not about a specific capitalization preference, but more a clear way to differentiate the scope from the function name

Sure why not, I don't like the current mix of underscores and dashes