Document missing OpenAPI/Swagger-Defintion/API-Spec

[andygrunwald]

One thought would be if we can generate this client.
An API Spec file would be required for it.
A few discussions have been ongoing, but no progress/merge yet regarding this topic.
See:

• Initial Issue Tracker Ticket: https://bugs.chromium.org/p/gerrit/issues/detail?id=11401&q=swagger&can=2
• ESC Meeting notes: https://www.gerritcodereview.com/2019-12-10-esc-minutes.html
• ESC Meeting notes: https://www.gerritcodereview.com/2020-01-21-esc-minutes.html

The goal of this task:
Document this in the README, that this client lib is manually created + that new API endpoints must be added manually.

[andygrunwald]

I had a quick chat with @phiesel about this topic.
Patrick was mentioned in the ESC minutes to be the person to look at the topic.
He said (quote):

we won't move to Swagger etc. any time soon because it fails the const/benefit tradeoff. Gerrit as you might know allows plugins to also expose REST APIs and it's not trivial to support this in exactly the same way with Swagger.

We will likely move our entity definitions to Protobuf so that callers can reuse the object definitions. All that's left to do then is use a proto2json mapper (those are widely available) and call the URLs. Surely, service definitions would be way nice than calling URLs with an HTTP framework, but it's hard to make the Gerrit server work with Swagger, etc.

[...]

Proto files will be open-source, so you can compile them into your binary in your language of choice.

What does this mean for us + this project right now?

I suggest we document the current status in the README + that we keep an eye on future Gerrit versions to add support for Protobuf.

[andygrunwald]

A quick/dirty idea:

Gerrits documentation is written in asciidoc: https://gerrit.googlesource.com/gerrit/+/refs/heads/master/Documentation/
The endpoints and content types are (more or less)unified.

Similar to go-github (https://github.com/google/go-github/blob/master/github/gen-accessors.go), we can create a go generate script that

• Checks if we have implemented all endpoints
• Verified we have all fields inside the Content-type structs

It won't be a good generate script, but more a "there is something missing" script.
Additionally, the documentation don't cover the types of the struct members.

github.com/bytesparadise/libasciidoc could be a library to parse the asciidoc on this.

Maybe the whole thing is a bit over-engineered.
However, it would keep us up to date with changes in gerrit as well (as long as they are documented in asciidoc).

Just posting this piece of code here for the future me to not start 100% from scratch:

package main

import (
	"fmt"
	"os"

	"github.com/bytesparadise/libasciidoc/pkg/configuration"
	"github.com/bytesparadise/libasciidoc/pkg/parser"
	"github.com/bytesparadise/libasciidoc/pkg/types"
)

func main() {
	filePath := "/Users/agrunwald/Development/gerrit/Documentation/rest-api-groups.txt"

	file, err := os.Open(filePath)
	if err != nil {
		panic(err)
	}
	defer file.Close()

	config := configuration.Configuration{}
	doc, err := parser.ParseDocument(file, config)
	if err != nil {
		panic(err)
	}

	for _, v := range doc.Elements {
		t := v.(types.Section)

		for _, sect := range t.Title {
			fmt.Print("%+v", sect)
		}
	}
}