Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Schema is missing payload contents #43

Closed
btorresgil opened this issue Sep 25, 2019 · 5 comments
Closed

Schema is missing payload contents #43

btorresgil opened this issue Sep 25, 2019 · 5 comments
Labels
Type: Feature New feature or request

Comments

@btorresgil
Copy link

In the generated schema there is only name, actions, and examples. The payload of the webhook is not pulled from the documentation. This results in major consequences down the chain as webhooks.js is derived from this, as is all the TypeScript typings for the webhooks.

This means that critical payload values that exist in the webhook are not accessible in TypeScript without some terrible escape hatches.

For example, in an IssuesEvent, a developer trying to access the label payload property would not get prompted that it exists:

2019-09-25_13-24-32

And entering it anyway results in a compiler error, even though the property exists in the webhook:

2019-09-25_13-25-00

The only workaround I've found is to override the types to add the missing properties when they are needed, or escape hatch with any:

webhooks.on('issues.labeled', ({payload}: {payload: any}) => {
  const label = payload.label
})

Since using any removes any type checking, it kinda defeats the purpose of having a schema. So it would be great if the schema could be complete enough to include all the payload parameters in the documentation.

Thanks!

@btorresgil
Copy link
Author

Also created issue octokit/webhooks.js#94 which depends on this issue.

@gr2m
Copy link
Contributor

gr2m commented Sep 25, 2019

The examples are payload examples and the Typescript definitions are later derived from these. Ideally we would have JSON Schema specifications for each webhook event but that's not happening anytime soon.

They payloads look different for different cases, sometime keys are included and sometimes not. The best we can do is to kindly ask support@github.com to extend the respective payload example.

What I would love to do is setup an automated recording of webhooks similar to how we record fixtures at https://github.com/octokit/fixtures, that way we can just add more scenarios to record more example payloads. But that will require a pretty major effort.

We are working on an OpenAPI spec for the REST APIs right now, once we have that, I hope we can work on JSON Specs for the webhooks next.

@gr2m
Copy link
Contributor

gr2m commented Sep 25, 2019

Another thing we could do is to derive a JSON Schema from the payload tables as you suggest and publish these next to the examples. I'd happily accept a pull request

@gr2m gr2m added the Type: Feature New feature or request label May 5, 2020
@wolfy1339
Copy link
Member

This should be resolved by #186

@gr2m
Copy link
Contributor

gr2m commented Jan 7, 2021

I think so, too. Please let us know if the problem persists

@gr2m gr2m closed this as completed Jan 7, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Type: Feature New feature or request
Projects
None yet
Development

No branches or pull requests

3 participants