feat: added grpc gateway annotations and review comments

Update the proto definition to explicitly state the http options for the grpc gateway. Also changed the names of the service methods and associated messages to follow the google naming conventions. Signed-off-by: Richard Case <[email protected]>
liquidmetal-dev · Aug 9, 2021 · d67e60e · d67e60e
1 parent 96c1347
commit d67e60e
Show file tree

Hide file tree

Showing 15 changed files with 954 additions and 485 deletions.
diff --git a/api/services/microvm/v1alpha1/microvms.pb.go b/api/services/microvm/v1alpha1/microvms.pb.go
diff --git a/api/services/microvm/v1alpha1/microvms.pb.gw.go b/api/services/microvm/v1alpha1/microvms.pb.gw.go
diff --git a/api/services/microvm/v1alpha1/microvms.proto b/api/services/microvm/v1alpha1/microvms.proto
@@ -5,57 +5,89 @@ package microvm.services.api.v1alpha1;
 import "google/protobuf/empty.proto";
 import "google/protobuf/any.proto";
 import "google/protobuf/field_mask.proto";
+import "google/api/annotations.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
 import "types/microvm.proto";
 
 option go_package = "github.com/weaveworks/reignite/api/services/microvm/v1alpha1";
 
+option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
+    info: {
+      title: "Reignite MicroVM API",
+      version: "0.1";
+      description: "The Reignite MicroVM API handles operations for provisioning and managing microvms";
+    };
+    consumes: "application/json";
+    produces: "application/json";
+};
+
 // MicroVM providers a service to create and manage the lifecycle of microvms.
 service MicroVM {
-  rpc Create(CreateRequest) returns (CreateResponse);
-  rpc Update(UpdateRequest) returns (UpdateResponse);
-  rpc Delete(DeleteRequest) returns (google.protobuf.Empty);
-  rpc Get(GetRequest) returns (GetResponse);
-  rpc List(ListRequest) returns (ListResponse);
-  rpc ListStream(ListRequest) returns (stream ListMessage);
+  rpc CreateMicroVM(CreateMicroVMRequest) returns (CreateMicroVMResponse) {
+    option (google.api.http) = {
+      post: "/v1alpha1/microvm"
+    };
+  }
+  rpc UpdateMicroVM(UpdateMicroVMRequest) returns (UpdateMicroVMResponse) {
+    option (google.api.http) = {
+      put: "/v1alpha1/microvm/{microvm.namespace}/{microvm.id}"
+    };
+  }
+  rpc DeleteMicroVM(DeleteMicroVMRequest) returns (google.protobuf.Empty) {
+    option (google.api.http) = {
+      delete: "/v1alpha1/microvm/{namespace}/{id}"
+    }; 
+  }
+  rpc GetMicroVM(GetMicroVMRequest) returns (GetMicroVMResponse) {
+    option (google.api.http) = {
+      get: "/v1alpha1/microvm/{namespace}/{id}"
+    };
+  }
+  rpc ListMicroVMs(ListMicroVMsRequest) returns (ListMicroVMsResponse) {
+    option (google.api.http) = {
+      get: "/v1alpha1/microvm/{namespace}"
+    };
+  }
+  rpc ListMicroVMsStream(ListMicroVMsRequest) returns (stream ListMessage);
 }
 
-message CreateRequest {
+message CreateMicroVMRequest {
   reignite.types.MicroVMSpec microvm = 1;
   map<string, google.protobuf.Any> metadata = 2;
 }
 
-message CreateResponse {
+message CreateMicroVMResponse {
   reignite.types.MicroVMSpec  microvm = 1;
 }
 
-message DeleteRequest {
+message DeleteMicroVMRequest {
   string id = 1;
   string namespace = 2;
 }
 
-message UpdateRequest {
+message UpdateMicroVMRequest {
   reignite.types.MicroVMSpec  microvm = 1;
   google.protobuf.FieldMask update_mask = 2;
 }
 
-message UpdateResponse {
+message UpdateMicroVMResponse {
   reignite.types.MicroVMSpec  microvm = 1;
 }
 
-message GetRequest {
+message GetMicroVMRequest {
   string id = 1;
   string namespace = 2;
 }
 
-message GetResponse {
+message GetMicroVMResponse {
   reignite.types.MicroVMSpec  microvm = 1;
 }
 
-message ListRequest {
-  optional string namespace = 2;
+message ListMicroVMsRequest {
+  string namespace = 1;
 }
 
-message ListResponse {
+message ListMicroVMsResponse {
   repeated reignite.types.MicroVMSpec  microvm = 1;
 }
 

diff --git a/api/services/microvm/v1alpha1/microvms.swagger.json b/api/services/microvm/v1alpha1/microvms.swagger.json
@@ -1,8 +1,9 @@
 {
   "swagger": "2.0",
   "info": {
-    "title": "services/microvm/v1alpha1/microvms.proto",
-    "version": "version not set"
+    "title": "Reignite MicroVM API",
+    "description": "The Reignite MicroVM API handles operations for provisioning and managing microvms",
+    "version": "0.1"
   },
   "tags": [
     {
@@ -15,7 +16,168 @@
   "produces": [
     "application/json"
   ],
-  "paths": {},
+  "paths": {
+    "/v1alpha1/microvm": {
+      "post": {
+        "operationId": "MicroVM_CreateMicroVM",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/v1alpha1CreateMicroVMResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "tags": [
+          "MicroVM"
+        ]
+      }
+    },
+    "/v1alpha1/microvm/{microvm.namespace}/{microvm.id}": {
+      "put": {
+        "operationId": "MicroVM_UpdateMicroVM",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/v1alpha1UpdateMicroVMResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "microvm.namespace",
+            "description": "Namespace is the name of the namespace the microvm belongs to.",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "microvm.id",
+            "description": "ID is the identifier of the microvm.\nIf this empty at creation time a ID will be automatically generated.",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          }
+        ],
+        "tags": [
+          "MicroVM"
+        ]
+      }
+    },
+    "/v1alpha1/microvm/{namespace}": {
+      "get": {
+        "operationId": "MicroVM_ListMicroVMs",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/v1alpha1ListMicroVMsResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "namespace",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          }
+        ],
+        "tags": [
+          "MicroVM"
+        ]
+      }
+    },
+    "/v1alpha1/microvm/{namespace}/{id}": {
+      "get": {
+        "operationId": "MicroVM_GetMicroVM",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "$ref": "#/definitions/v1alpha1GetMicroVMResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "namespace",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          }
+        ],
+        "tags": [
+          "MicroVM"
+        ]
+      },
+      "delete": {
+        "operationId": "MicroVM_DeleteMicroVM",
+        "responses": {
+          "200": {
+            "description": "A successful response.",
+            "schema": {
+              "properties": {}
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "namespace",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "type": "string"
+          }
+        ],
+        "tags": [
+          "MicroVM"
+        ]
+      }
+    }
+  },
   "definitions": {
     "HostPathVolumeSourceHostPathType": {
       "type": "string",
@@ -220,15 +382,15 @@
       },
       "description": "VolumeSource is the source of a volume. Based loosely on the volumes in Kubernetes Pod specs."
     },
-    "v1alpha1CreateResponse": {
+    "v1alpha1CreateMicroVMResponse": {
       "type": "object",
       "properties": {
         "microvm": {
           "$ref": "#/definitions/typesMicroVMSpec"
         }
       }
     },
-    "v1alpha1GetResponse": {
+    "v1alpha1GetMicroVMResponse": {
       "type": "object",
       "properties": {
         "microvm": {
@@ -244,7 +406,7 @@
         }
       }
     },
-    "v1alpha1ListResponse": {
+    "v1alpha1ListMicroVMsResponse": {
       "type": "object",
       "properties": {
         "microvm": {
@@ -255,7 +417,7 @@
         }
       }
     },
-    "v1alpha1UpdateResponse": {
+    "v1alpha1UpdateMicroVMResponse": {
       "type": "object",
       "properties": {
         "microvm": {