OpenAPI support for endpoint introspection

[penberg]

Let's add support for OpenAPI to allow Swagger or Postman introspection of the endpoints.

[penberg]

@dekimir Suggest to add TypeScript decorators for describing the shape of the endpoint inputs and outputs.

[glommer]

this must be optional. Something we work well without (in which case we show the result of chisel describe), but better with it (in which case we show the swagger API)

[glommer]

@mpdehaan just opened this, which may be relevant, Pekka : #983

[penberg]

Update: pretty much everybody hits the issue of not finding the correct URL for their endpoints when deploying to the ChiselStrike platform. We need this introspection support to show the endpoints in the web UI.

[glommer]

Although OpenAPI would be nice, this is not strictly necessary to solve the user's issue.
We can show the output of chisel describe <version> in the frontend. This will show which endpoints are available, which models, and which policies (which openAPI wouldn't show anyway).

It may be advisable to change that output to json so we can show models, endpoints and policies separately.

That's not to say OpenAPI won't make things better (as it will include documentation for the endpoints as well), but we should do something to show the output of describe as well.

[penberg]

@glommer OpenAPI is not an issue at all here. I can trivially generate an OpenAPI JSON with the endpoint paths. The real issue is that those paths don't translate into meaningful developer experience. You need to know what HTTP methods they support at minimum and preferrably you should also know what kind of parameters they accept.

You do, however, have a point that perhaps we should indeed do something simple now to address the issue of people tripping over wrong URLs all the time.

@glommer Would you prefer chisel describe and some backend wrapping or shall we go for simple OpenAPI directly, which shows the paths, but not the HTTP methods?

[glommer]

if we can generate basic openapi skeletons that just show the endpoint names without user change, then we can do it. (I don't know enough).

Otherwise we should go with the describe route

[penberg]

There's now preliminary support for OpenAPI added in commit a3e5944

[mpdehaan]

(ignore my comments I deleted on this one, seeing I thought it was the other ticket that got closed)

[penberg]

I am closing this as we support OpenAPI. There's a follow-up issue #1071 to make the APIs more discoverable.