OpenAPI Spec

[WyriHaximus]

What’s missing?

An OpenAPI spec YAML file for the payload-schemas.

Why?

Because it will bring having the webhook schema definitions in the official OpenAPI spec one step over: github/rest-api-description#21

Alternatives you tried

Tried converting the JSON Schema file with several tools, but they all failed when getting into the second level of object properties.

[wolfy1339]

I don't think adding a YAML version would be in the plans. If someone needs it they can make one by converting the JSON.

This would require substantial changes. We currently have separate schemas for each event's actions, and then we merge them together as one single file (with some slight modifications) during the build process.

Would you be willing to help out if we decide to integrate OpenAPI?

[wolfy1339]

@G-Rath @gr2m Any thoughts?

[WyriHaximus]

I don't think adding a YAML version would be in the plans. If someone needs it they can make one by converting the JSON.

Tried that last night and got stuck at some point. If you have a way to get a correctly converted YAML I'm interested.

This would require substantial changes. We currently have separate schemas for each event's actions, and then we merge them together as one single file (with some slight modifications) during the build process.

Looking at the code and spec that comes out of it both JSON Schema and OpenAPI seems very similar.

Would you be willing to help out if we decide to integrate OpenAPI?

Was already looking at how the project is set up and works, so yes 👍 .

@G-Rath @gr2m Any thoughts?

@gr2m is the one pointing me over here: github/rest-api-description#21 (comment)

[wolfy1339]

I don't think adding a YAML version would be in the plans. If someone needs it they can make one by converting the JSON.

Tried that last night and got stuck at some point. If you have a way to get a correctly converted YAML I'm interested.

You're asking for an OpenAPI YAML version. I'm saying that we could provide a JSON version, but I'm unsure if we would provide a YAML version

Looking at the code and spec that comes out of it both JSON Schema and OpenAPI seems very similar.

The schemas, as they are currently, can almost be used in OpenAPI but there are some small differences.

Would you be willing to help out if we decide to integrate OpenAPI?

Was already looking at how the project is set up and works, so yes 👍

I made a simple conversion, and it includes a YAML version here: https://github.com/octokit/webhooks/tree/openapi
It really isn't the best, and isn't spec compliant due to the fact that we are using a custom property that isn't prefixed with x-

[WyriHaximus]

I don't think adding a YAML version would be in the plans. If someone needs it they can make one by converting the JSON.

Tried that last night and got stuck at some point. If you have a way to get a correctly converted YAML I'm interested.

You're asking for an OpenAPI YAML version. I'm saying that we could provide a JSON version, but I'm unsure if we would provide a YAML version

Ah that way, don't mind at all if a JSON or a YAML, sorry for the confusion.

Looking at the code and spec that comes out of it both JSON Schema and OpenAPI seems very similar.

The schemas, as they are currently, can almost be used in OpenAPI but there are some small differences.

That might explain some of my confusion 😂 .

Would you be willing to help out if we decide to integrate OpenAPI?

Was already looking at how the project is set up and works, so yes 👍

I made a simple conversion, and it includes a YAML version here: https://github.com/octokit/webhooks/tree/openapi
It really isn't the best, and isn't spec compliant due to the fact that we are using a custom property that isn't prefixed with x-

If and how can I help to improve it?

[wolfy1339]

If and how can I help to improve it?

A proper implementation without all the hackyness that can validate against the OpenAPI spec.
My conversion is a proof-of-concept and should only be used as a base

[gr2m]

@G-Rath @gr2m Any thoughts?

@gr2m is the one pointing me over here: github/rest-api-description#21 (comment)

Both a YAML output and OpenAPI spec is out of scope of this repository. This is a community effort, not driven by any GitHub employees. If you'd like to build upon this repository and create an OpenAPI spec in a YAML format on it, you'd need to do it yourself.

But the core part that is hard to create and maintain are the JSON Schemas for all the webhook requests, and that's what @wolfy1339 and the others invested a lot of time into already

[WyriHaximus]

If and how can I help to improve it?

A proper implementation without all the hackyness that can validate against the OpenAPI spec.
My conversion is a proof-of-concept and should only be used as a base

vs.

@gr2m is the one pointing me over here: github/rest-api-description#21 (comment)

Both a YAML output and OpenAPI spec is out of scope of this repository. This is a community effort, not driven by any GitHub employees. If you'd like to build upon this repository and create an OpenAPI spec in a YAML format on it, you'd need to do it yourself.

Those two statements seem conflicting. My main intention is to bridge to time from now until GitHub will provide these schema's. I'm game for helping put, initial check uncovered I can't currently parse https://github.com/octokit/webhooks/blob/openapi/payload-schemas/openapi-schema.yml due to a missing request body (user). But if it's out of scope of this repository I also don't want to spent to much time on it.

But the core part that is hard to create and maintain are the JSON Schemas for all the webhook requests, and that's what @wolfy1339 and the others invested a lot of time into already

❤️ !

[wolfy1339]

In #136 (comment)

For future reference, we might consider changing the format of the published assets to follow the OpenAPI 3.1 specification for webhooks.

There seemed to be a willingness in the past for changing to OpenAPI

Before GitHub published their own OpenAPI spec, there was @octokit/routes which was a community maintained OpenAPI spec for the REST api.

I just demonstrated a quick and easy solution to publishing an OpenAPI spec for those who need it. There's no need to change the input format or anything

---

due to a missing request body (user). But if it's out of scope of this repository I also don't want to spent to much time on it.

That is definitely a bug. I just fixed it

[gr2m]

fyi as of v2.1.0, GitHub's OpenAPI spec includes webhooks. I didn't look into it in detail, just sharing the announcement

https://github.com/github/rest-api-description/releases/tag/v2.1.0

[wolfy1339]

🎉 That's amazing news!

How should we handle the transition in this repo, since there's now official openapi spec?

[gr2m]

From my experience with transitioning https://github.com/octokit/routes where we generated an OpenAPI Spec to github.com/octokit/openapi where we utilize GitHub's OpenAPI spec, there will be some discrepancies, I'm sure the first version of the webhooks in the OpenAPI spec will lack some things that we have in our specs.

I'd start out by creating a setup where we load GitHub's new OpenAPI spec and compare them to ours, to find these discrepancies. Once they are compatible, I guess we can just switch? We could still allow for user-patches in order to fill gaps until problems are resolved on GitHub's side, I've imlemented something similar in octokit/openapi. But we can look into that later