Add OpenAPI definition for the API

[inferno-chromium]

Requested in https://twitter.com/PermittedSoc/status/1646389772577824768

[MikeRalphson]

Happy to help review / collaborate. Thanks.

[ioggstream]

metoo!

[adg]

Thanks for the feature request. Can I ask about the intended use cases? Is it so that API client code can be auto-generated?

[MikeRalphson]

Partly, mainly for ease of consuming / validating the documentation. I run the Apis.guru OpenAPI directory. We could also convert from a Google discovery format file.

[ioggstream]

OAS can be used for various purposes, including:

• interactive documentation purposes: it can be rendered by UIs using a standard presentation format (e.g. se editor.swagger.io)
• client code generation
• data model validation
• catalogs.

Thanks for asking, R.

[benken-parasoft]

Please allow me to provide some justification for this request.

I just spent an afternoon manually converting https://docs.deps.dev/api/ to an OpenAPI definition. I was typing the whole thing by hand using Swagger Editor. This was very tedious, especially coding all the JSON Schema type definitions. The document became ~625 lines when done, also including the descriptions for each operation, parameter, and JSON Schema type. I am also not sure I got the "format" right on everything. Things that are a "number" I assume are probably "type: integer" and "format: int32" but this is just my guess. Additionally, some strings are URLs where I initially used "format: uri" but I found that the "links" returned in GetVersion sometimes fail to parse as such.

In my case, I was doing this for my own client code generation. This also simplifies stubbing out or mocking response objects when writing unit tests. There is a bit of tooling already available for OpenAPI and JSON Schema. So, I do not really need a special client library for an API when all I really need is an OpenAPI definition that describes the API.

[sschuberth]

I just spent an afternoon manually converting https://docs.deps.dev/api/ to an OpenAPI definition.

Mind sharing that work somewhere? Thanks in advance!

[benken-parasoft]

Mind sharing that work somewhere?

deps_dev.yaml.txt

(Updated March 28, 2024 for v3 with "ossFuzz" now in response object for GetProject.)

[sarnesjo]

A long overdue update on this issue!

Having a formal API definition is certainly a good thing. For us, as a Google team, the gRPC service definition is it. While our API is accessible via gRPC and HTTP, it's actually a single implementation under the hood, with the latter transcoded to and from the former. The API documentation is also generated from the same definition. This is how we ensure it all stays in sync.

Additionally providing an OpenAPI definition for the HTTP API would be nice, but since OpenAPI is not part of our setup, we'd need to have a reliable way to generate it from the gRPC service definition, including regenerating it when needed, and be confident that it's correct and won’t drift over time. We did experiment with this, using protoc-gen-openapi, but unfortunately found that it did not generate correct output.

Fwiw, we have just updated the published gRPC service definition to include HTTP annotations, which define how gRPC methods are mapped to URLs. This means that it's now possible for anyone to generate HTTP client code from the gRPC service definition alone.