search

authzed / api

Protocol Buffers & gRPC Services used by SpiceDB
https://authzed.com/docs
Apache License 2.0
16 stars 18 forks source link

Generate OpenAPI definitions for HTTP API #117

Open tstirrat15 opened 2 months ago

tstirrat15 commented 2 months ago

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 commented 3 weeks ago

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: https://github.com/authzed/authzed-go/pull/255

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