[FR] Provide OpenAPI/Swagger file

[rafamel]

This would be very helpful to generate SDKs or typecheck api calls to AuthN in languages for which an SDK is not officially provided (so other than go and ruby).

If it exists, I haven't been able to locate it; would you consider making it public/providing it?

[mohammed90]

Well, the work in PR #83 can help with this. We're using gRPC-Gatway there, whose protoc-plugin can generate Swagger files. I haven't included Swagger file as part of the PR because we haven't agreed on it and outside the scope of the PR.

If this feature request is accepted its inclusion can be pretty simple by just including the protoc-plugin in the Makefile and a few sed.

[cainlevy]

We can also use gRPC to generate clients directly without Swagger, right?

Clients will still need a token verifier, of course.

[silasdavis]

I'm using swagger for our project Pericyte as a library. It's quite nice to use the generated typescript/axios javascript client there, would be nice if the keratin endpoints had similar definition.

Generating from protoc is a good option, then we can all have clients from a single definition.

[silasdavis]

I came across this recently that is worth considering for this purpose too: https://github.com/googleapis/gnostic

[rafamel]

On this, if it is trivial, as said by @mohammed90, to include the swagger/openapi files, that would be great to have. There's a lot of tooling around swagger/openapi for everything imaginable and it's more widespread than gRPC/gRPC tooling, so if it doesn't require much of an effort, for me at least -and I'm sure to bet for many others- it'd be insane useful.

Is there any intent on moving this forwards?

[cainlevy]

I'm receptive to seeing what an OpenAPI spec for AuthN's RESTful endpoints would look like. I would like to see it as a replacement for the existing API doc, with similar maintenance costs.

Note that it may be valuable to have two separate API specifications, one for client (e.g. JavaScript) integration and another for server (e.g. Ruby, Go) integration.

That said, I want to caution again that generating server clients from an API spec will not yield a fully functioning AuthN integration. Token verification and keychain management are still necessary features.

[cainlevy]

Also: this may still end up replaced by gRPC tooling, but if someone wants to move it along in parallel then it's fine with me.