docs(api): Document feedback endpoint

go-amizone · Nov 27, 2023 · 07e4fc4 · 07e4fc4
1 parent e84d9a9
commit 07e4fc4
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 0 deletions.
diff --git a/server/gen/go/v1/amizone_grpc.pb.go b/server/gen/go/v1/amizone_grpc.pb.go
diff --git a/server/gen/openapiv2/v1/amizone.swagger.json b/server/gen/openapiv2/v1/amizone.swagger.json
@@ -261,6 +261,8 @@
     },
     "/api/v1/faculty/feedback/submit": {
       "post": {
+        "summary": "FillFacultyFeedback submits faculty feedback.",
+        "description": "It does so by making a tradeoffs -- all faculty feedback is submitted at\nonce and its identical for all of them.\n\nParameters:\n- rating: The rating to submit for all faculty. These are ratings on a scale of 1-5.\n- query_rating: The rating to \"query\" type questions at the bottom of the feedback form.\n  These are ratings on a scale of 1-3.",
         "operationId": "AmizoneService_FillFacultyFeedback",
         "responses": {
           "200": {
@@ -351,6 +353,7 @@
     },
     "/api/v1/wifi_mac": {
       "get": {
+        "summary": "GetWifiMacInfo returns the user's registered MAC addresses.",
         "operationId": "AmizoneService_GetWifiMacInfo",
         "responses": {
           "200": {
@@ -375,6 +378,7 @@
         ]
       },
       "post": {
+        "summary": "RegisterWifiMac registers a MAC address to the user's account.",
         "operationId": "AmizoneService_RegisterWifiMac",
         "responses": {
           "200": {
@@ -411,6 +415,7 @@
     },
     "/api/v1/wifi_mac/{address}": {
       "delete": {
+        "summary": "DeregsiterWifiMac removes a registered MAC address from the user's account.",
         "operationId": "AmizoneService_DeregisterWifiMac",
         "responses": {
           "200": {

diff --git a/server/proto/v1/amizone.proto b/server/proto/v1/amizone.proto
@@ -98,18 +98,30 @@ service AmizoneService {
   rpc GetUserProfile(EmptyMessage) returns (Profile) {
     option (google.api.http) = {get: "/api/v1/user_profile"};
   }
+  // GetWifiMacInfo returns the user's registered MAC addresses.
   rpc GetWifiMacInfo(EmptyMessage) returns (WifiMacInfo) {
     option (google.api.http) = {get: "/api/v1/wifi_mac"};
   }
+  // RegisterWifiMac registers a MAC address to the user's account.
   rpc RegisterWifiMac(RegisterWifiMacRequest) returns (EmptyMessage) {
     option (google.api.http) = {
       post: "/api/v1/wifi_mac"
       body: "*"
     };
   }
+  // DeregsiterWifiMac removes a registered MAC address from the user's account.
   rpc DeregisterWifiMac(DeregisterWifiMacRequest) returns (EmptyMessage) {
     option (google.api.http) = {delete: "/api/v1/wifi_mac/{address}"};
   }
+  // FillFacultyFeedback submits faculty feedback.
+  //
+  // It does so by making a tradeoffs -- all faculty feedback is submitted at
+  // once and its identical for all of them.
+  //
+  // Parameters:
+  // - rating: The rating to submit for all faculty. These are ratings on a scale of 1-5.
+  // - query_rating: The rating to "query" type questions at the bottom of the feedback form.
+  //   These are ratings on a scale of 1-3.
   rpc FillFacultyFeedback(FillFacultyFeedbackRequest) returns (FillFacultyFeedbackResponse) {
     option (google.api.http) = {
       post: "/api/v1/faculty/feedback/submit",