Gerrit

[Monorail components: Backend]

It was already proposed years ago on the mailing list at: https://groups.google.com/forum/#!topic/repo-discuss/ORNnk6WhaaY/discussion

I believe it's a good idea, so that Gerrit API could become more friendly and self-documented.
Also, it would reduce the burden of creating and maintaining client-side libraries in different languages, currently done manually.

[Empty comment from Monorail migration]

Raising for discussion to the ESC

[Monorail components: ESC]

We discussed this in the ESC meeting this week.  Patrick will follow up with research on whether Swagger is a good fit, or if there's any alternative.

i would love to see this (or equiv).  CrOS, like i'm sure everyone else here, as a custom bespoke Python implementation of the Gerrit REST API and i want nothing more but to delete it all and replace with a single authoritative one.

+1 to @Vapier comment.

Also in Java the support is very much ad-hoc with "copy&paste" from Gerrit code-base into a separate project on GitHub, which isn't a very good and maintainable approach.

Having an OpenAPI definition would allow to easily generate stubs for any language, without any "copy&paste" around.

[Monorail components: -ESC]

[Empty comment from Monorail migration]

I know this is probably not high priority as a new feature, but I thought I'd drop by and express how much this would improve language interoperability with the API. For example, Go has a manually-written REST client, which is just glue code to declare the struct types and send them along to the right HTTP endpoint. And they have to be manually kept in sync with upstream; for example, it took me a good fifteen minutes to write https://github.com/andygrunwald/go-gerrit/pull/123 to add some new fields to just one of the structs.

All of this could be entirely automated with an OpenApi definition - not just for Go, but for practically any language that supports REST :)

[Comment Deleted]

While a fully implemented Swagger definition might be too much to chew, that doesn't mean there aren't benefits completing the work incrementally. E.g.: 4XX messages could be improved with jsonschema validation.

Hello,

I did a small PoC, deriving the request and response information of some API calls from the REST-API documentation (e.g. Documentation/rest-api-changes.html). I did this via copy&paste from the HTML page into a tool like "stoplight", then generating the Swagger file.
Now I'm wondering how the Gerrit REST-API documention is created in general. Where is it generated from? Couldn't it be somehow automated, that we could a generate the complete Gerrit REST-API in Swagger format (and I could get rid of my manual copy&paste operations)?
Would be happy to get information where to dig into deeper.

Regards Herbert

Thanks for looking into this! The Gerrit REST-API documentation is currently hand-written. We agree that it would be better to generate it, but we don't have that yet.