build: generate OpenAPI from grpc

[erka]

Use google/gnostic to generate OpenAPI v3 schema base on the proto files.

This PR has mixed option (google.api.http) and grpc_api_configuration=rpc/flipt/flipt.yaml together. If the path should be included into OpenAPI spec it should be use google.api.http for path configuration

Issues:

• what is the best place for openapi.yaml
• how to check impact of replacement github.com/google/gnostic/openapiv3 with github.com/google/gnostic-models/openapiv3
• OpenAPI security settings probably doesn't have all options
• legacy evaluation endpoints are missing. Is it a problem?
• should OFREP endpoints be part of Flipt OpenAPI?

related flipt-io/flipt-openapi/issues/25

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 64.44%. Comparing base (87ca6e8) to head (de99bd4).
Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3357      +/-   ##
==========================================
+ Coverage   64.41%   64.44%   +0.02%     
==========================================
  Files         172      172              
  Lines       13820    13820              
==========================================
+ Hits         8902     8906       +4     
+ Misses       4234     4232       -2     
+ Partials      684      682       -2     

Flag	Coverage Δ
unittests	64.44% <ø> (+0.02%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[markphelps]

Looks great! just replying to some of your questions in the PR description:

what is the best place for openapi.yaml

I think at the root of the project? We could setup an action maybe to copy it over to https://github.com/flipt-io/flipt-openapi which drives the updates in our docs, or maybe just remove flipt-openapi altogether and update the docs action to pull the file from here?

It seems that Mintlify can pull the openapi spec from anywhere, so maybe we can give it a link to the raw file on GitHub at the root?

legacy evaluation endpoints are missing. Is it a problem?

No. We don't want to show the legacy evaluation endpoints.

should OFREP endpoints be part of Flipt OpenAPI?

Yes. I think we should add this as part of the OpenAPI docs

[GeorgeMac]

I think this is great @erka 🙌 Awesome catch. Yeah, I think as Mark suggested, maybe get it into the root of the project? Then lets get it in 💪

[erka]

@markphelps could I rename operation_id for OpenApi?

[markphelps]

@markphelps could I rename operation_id for OpenApi?

@erka how do you mean? do you mean for OFREP? or something else?

[erka]

how do you mean? do you mean for OFREP? or something else?

I played a bit with other side of OpenApi generation and I would like to make the api a bit nicer there. For example, we have such operation_ids currently

 /api/v1/namespaces:
        get:
            tags:
                - Flipt
            operationId: NamespacesService.list
--- omitted ---
/ofrep/v1/evaluate/flags/{key}:
        post:
            tags:
                - OFREPService
            operationId: ofrep.evaluate

After code generation, I get the client with the methods

func main() {
	client, _ := gen.NewClientWithResponses("http://localhost:8080")

	client.NamespacesServiceList(context.TODO(), ...)

	client.OfrepEvaluate(context.TODO(), "flag", ...)
}

It isn't very clear for me what NamespacesServiceList does and I prefer GetNamespaces method there but that may be a breaking changes for someone who uses current OpenApi spec.

@markphelps wdyt?

[markphelps]

how do you mean? do you mean for OFREP? or something else?

I played a bit with other side of OpenApi generation and I would like to make the api a bit nicer there. For example, we have such operation_ids currently

 /api/v1/namespaces:
        get:
            tags:
                - Flipt
            operationId: NamespacesService.list
--- omitted ---
/ofrep/v1/evaluate/flags/{key}:
        post:
            tags:
                - OFREPService
            operationId: ofrep.evaluate

After code generation, I get the client with the methods

func main() {
	client, _ := gen.NewClientWithResponses("http://localhost:8080")

	client.NamespacesServiceList(context.TODO(), ...)

	client.OfrepEvaluate(context.TODO(), "flag", ...)
}

It isn't very clear for me what NamespacesServiceList does and I prefer GetNamespaces method there but that may be a breaking changes for someone who uses current OpenApi spec.

@markphelps wdyt?

I think that's fine, although I would suggest ListNamespaces

[markphelps]

lgtm! thank you @erka !!