Generate OpenAPI definitions for HTTP API

[tstirrat15]

Problem Statement

We have a Postman collection, but updating it is a manual task.

Additionally, we have users who want to use HTTP clients but also want type safety for those clients. If we export OpenAPI definitions, we can let users generate a typed API client using their tool of choice.

Solution Brainstorm

I'm not entirely sure where in the toolchain this should live - if it's a build-time thing that generates a static file or if it becomes something that's served alongside the HTTP API. I think I'd lean towards the latter but I'm not entirely sure.

[holgerstolzenberg]

I am currently exactly facing this problem.

I started to put together a GitHub project that provides these prepackaged clients: https://github.com/ewerk/authzed-http-client

It is currently incubating but snapshot libs for Java and Typescript are already available.

Essentially it is a a collection of GitHub actions leveraging https://github.com/openapi-generators/openapitools-generator-action. It uses the OpenAPI spec file that you already create from authzed/api into authzed/go.

Please see following PR for reference: authzed/authzed-go#255

If you are interested we could shift the project into authzed project responsibility once it has the necessary maturity.