Add Kubeapps apis docs #2885

antgamdia · 2021-05-25T17:54:25Z

PR in progress, just for showing the current changes.

Description of the change

We will have a way to automatically generate our API docs. After importing the OpenAPI file in any tool we will get a ready-to-use client, for instance:

Benefits

We will have automatic API docs!

Possible drawbacks

N/A, but once integrated as "official" docs, we should think about how to integrate it with the existing Kubeapps API docs

Applicable issues

fixes [kubeapps-apis] coreServer and/or plugins should serve swagger #2859

Additional information

~~I still need to work on defining the proper annotations, like: ~~ DONE

An example of how to use the OAS document to easily consume the API :

antgamdia · 2021-05-25T17:55:27Z

cmd/kubeapps-apis/buf.lock

+    commit: 2e73676eef8642dfba4ed782b7c8d6fe
+    digest: b1-vB11w98W2vFtEP4Veknm56Pi6DU6MpOuocESiOzvbqw=
+    create_time: 2021-04-26T14:55:30.644663Z


I wasn't able to replicate your issue, @absoludity . I did type buf beta mod updata and then buf generate without any error :S

Excellent, I'll recheck locally once this lands and update the issue I created.

antgamdia · 2021-05-25T17:58:07Z

cmd/kubeapps-apis/buf.gen.yaml

+  # https://github.com/grpc-ecosystem/grpc-gateway/pull/2147
+  - name: openapiv2
+    out: docs
+    strategy: all


It was the key point for allow_merge to work...
For the record, the default value is directory, so the merge logic, in each folder, was overwriting the file again and again.
Anyway, it was worthwhile as I have learned a bit more about buf :P

Nice - so we can combine/merge the schema docs without needing the (npm-based) swagger-combine? Excellent if so!

antgamdia · 2021-05-25T17:59:32Z

cmd/kubeapps-apis/buf.gen.yaml

+      # - generate_unbound_methods=true # have to re-check it
+      # - json_names_for_fields=false # have to re-check it


I have to see the impact of these options. I have screened the ones that other people are using in other github projects, but I have to re-check when playing around with the generate API docs

absoludity

Excellent, very happy to see a single doc without swagger-combine :) +1'ing now just in case you only need minor changes and I'm not around.

absoludity · 2021-05-25T22:29:44Z

cmd/kubeapps-apis/buf.gen.yaml

+  # https://github.com/grpc-ecosystem/grpc-gateway/pull/2147
+  - name: openapiv2
+    out: docs
+    strategy: all


Nice - so we can combine/merge the schema docs without needing the (npm-based) swagger-combine? Excellent if so!

absoludity · 2021-05-25T22:33:12Z

cmd/kubeapps-apis/buf.lock

+    commit: 2e73676eef8642dfba4ed782b7c8d6fe
+    digest: b1-vB11w98W2vFtEP4Veknm56Pi6DU6MpOuocESiOzvbqw=
+    create_time: 2021-04-26T14:55:30.644663Z


Excellent, I'll recheck locally once this lands and update the issue I created.

absoludity · 2021-05-25T22:35:23Z

cmd/kubeapps-apis/docs/kubeapps-apis.swagger.json

+{
+  "swagger": "2.0",
+  "info": {
+    "title": "kubeappsapis/core/packages/v1alpha1/packages.proto",


Looks like the info defines this as core.packages.v1alpha1 only, whereas its describing others too (like core.plugins.v1alpha1 and plugins.fluxv2.packages.v1alpha1 etc.)?

Conflicts: cmd/kubeapps-apis/proto/kubeappsapis/core/plugins/v1alpha1/plugins.proto

antgamdia · 2021-05-26T16:51:01Z

...apps-apis/proto/kubeappsapis/plugins/kapp_controller/packages/v1alpha1/kapp_controller.proto

@@ -4,15 +4,30 @@ option go_package = "github.com/kubeapps/kubeapps/cmd/kubeapps-apis/gen/plugins/

 import "google/api/annotations.proto";
 import "kubeappsapis/core/packages/v1alpha1/packages.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";

 service PackagesService {


Question here, @absoludity : is it possible to safely change this service name to something like kappController_PackagesService ?

The generator is not able to deal with duplicated service names and we have to manually disambiguate the operation_id

Yes, I think KappControllerPackagesService should be fine. The only restriction buf lint puts on is that it needs to end in Service, from memory. Feel free to update to that (and Fluxv2PackagesService) and see if that fixes it before landing. Check buf lint too.

antgamdia · 2021-05-26T16:56:44Z

Initial version done! I have a minor question (as a comment), just to avoid using things like this to disambiguate names.

 option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      operation_id: "xxxxxxx";
...

Apart from that, I've tried to stick to the comments as much as possible (instead of using options) as it is much clearer IMO). The structure, therefore is:

// Title of the message
//
// Description of the message
message xxxxxxxxxx {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    example: '{ a json example of the object }'
  };
  // Title of the message field (except if it is a XXXXRequest, since they have no title, just description)
  //
  // Description of the message field
  XXXX xxx = 1;
}

absoludity

Great!

absoludity · 2021-05-27T05:11:19Z

...apps-apis/proto/kubeappsapis/plugins/kapp_controller/packages/v1alpha1/kapp_controller.proto

@@ -4,15 +4,30 @@ option go_package = "github.com/kubeapps/kubeapps/cmd/kubeapps-apis/gen/plugins/

 import "google/api/annotations.proto";
 import "kubeappsapis/core/packages/v1alpha1/packages.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";

 service PackagesService {


Yes, I think KappControllerPackagesService should be fine. The only restriction buf lint puts on is that it needs to end in Service, from memory. Feel free to update to that (and Fluxv2PackagesService) and see if that fixes it before landing. Check buf lint too.

absoludity · 2021-05-27T05:12:19Z

Sorry, probably conflicts (and two extra doc comments) to update when I landed my PR.

Conflicts: cmd/kubeapps-apis/gen/core/packages/v1alpha1/packages.pb.go cmd/kubeapps-apis/proto/kubeappsapis/core/packages/v1alpha1/packages.proto

antgamdia added 3 commits May 25, 2021 19:35

Add protoc-gen-openapiv2 into the project

e192c87

Configure openapiv2 buf plugin

758bb22

Add very initial openapi file

582f762

antgamdia commented May 25, 2021

View reviewed changes

absoludity approved these changes May 25, 2021

View reviewed changes

antgamdia added 3 commits May 26, 2021 18:31

Add openapi annotations

13ca94e

Merge branch 'master'

4d318da

Conflicts: cmd/kubeapps-apis/proto/kubeappsapis/core/plugins/v1alpha1/plugins.proto

Add generated files

918b35e

antgamdia commented May 26, 2021

View reviewed changes

antgamdia marked this pull request as ready for review May 26, 2021 16:51

absoludity approved these changes May 27, 2021

View reviewed changes

antgamdia added 7 commits May 27, 2021 12:22

Merge branch 'master'

2100d98

Conflicts: cmd/kubeapps-apis/gen/core/packages/v1alpha1/packages.pb.go cmd/kubeapps-apis/proto/kubeappsapis/core/packages/v1alpha1/packages.proto

Add generated files

1a574f4

Add more docs

f1a9172

Rename svc from the plugins

93bdaa3

Remove base_path

64ba982

Fix leftover

ca8ca78

Changes in go after rename in proto

d19074f

antgamdia merged commit 0b445d3 into vmware-tanzu:master May 28, 2021

antgamdia deleted the kubeapps-apis-docs branch May 28, 2021 15:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Kubeapps apis docs #2885

Add Kubeapps apis docs #2885

antgamdia commented May 25, 2021 •

edited

antgamdia May 25, 2021

absoludity May 25, 2021

antgamdia May 25, 2021

absoludity May 25, 2021

antgamdia May 25, 2021

absoludity left a comment

absoludity May 25, 2021

absoludity May 25, 2021

absoludity May 25, 2021

antgamdia May 26, 2021

absoludity May 27, 2021

antgamdia commented May 26, 2021 •

edited

absoludity left a comment

absoludity May 27, 2021

absoludity commented May 27, 2021

		# - generate_unbound_methods=true # have to re-check it
		# - json_names_for_fields=false # have to re-check it

Add Kubeapps apis docs #2885

Add Kubeapps apis docs #2885

Conversation

antgamdia commented May 25, 2021 • edited

Description of the change

Benefits

Possible drawbacks

Applicable issues

Additional information

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

absoludity left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

antgamdia commented May 26, 2021 • edited

absoludity left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

absoludity commented May 27, 2021

antgamdia commented May 25, 2021 •

edited

antgamdia commented May 26, 2021 •

edited