feat(openapi): add x-stage extension to public endpoints (#503)

Because - This feature was recommended in order to build the C# SDK from the OpenAPI docs. This will warn SDK users about the stage of the endpoint. This commit - Adds extension and documents the convention. --------- Co-authored-by: droplet-bot <[email protected]>
instill-ai · Oct 31, 2024 · 350332d · 350332d
1 parent 3cc5fbe
commit 350332d
Show file tree

Hide file tree

Showing 7 changed files with 912 additions and 114 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -18,7 +18,7 @@ Buffers](https://protobuf.dev/). The proto files are the source from which
 different code is auto-generated (e.g., language SDKs, OpenAPI
 specification of the contracts).
 
-### OpenAPI contracts
+### OpenAPI Contracts
 
 All the public endpoints are exposed in a single service
 ([`api-gateway`](https://github.com/instill-ai/api-gateway)]). These
@@ -29,7 +29,7 @@ format](../openapi/v2/service.swagger.yaml) and publicly available at
 auto-generated via [`grpc-gateway`](https://grpc-ecosystem.github.io/grpc-gateway/)
 and it only reflects the protobuf specification.
 
-## Codebase contribution
+## Codebase Contribution
 
 The Instill AI contracts follow most of the guidelines provided by [Google
 AIP](https://google.aip.dev/) but have made adjustments in certain areas
@@ -99,14 +99,40 @@ rpc UpdateNamespacePipeline(UpdateNamespacePipelineRequest) returns (UpdateNames
         patch: "/v1beta/namespaces/{namespace_id}/pipelines/{pipeline_id}"
         body: "pipeline"
     };
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "💧 VDP"};
 }
 ```
 
 [openapi.instill.tech](https://openapi.instill.tech) will render each part
 as the endpoint title (which can also used in the search engine) and the
 description in the endpoint's view.
 
+### Swagger Extensions
+
+The [Swagger
+Extension](https://swagger.io/docs/specification/2-0/swagger-extensions/)
+`x-stage` **MUST** be present in every **public** method for endpoints in
+_alpha_ or _beta_ stage. This extension can be added with the
+`openapiv2_operation` option:
+
+```proto
+// Get a pipeline
+//
+// Returns the details of a pipeline.
+rpc GetNamespacePipeline(GetNamespacePipelineRequest) returns (GetNamespacePipelineResponse) {
+    option (google.api.http) = {get: "/v1beta/namespaces/{namespace_id}/pipelines/{pipeline_id}"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+    tags: "💧 VDP"
+    extensions: {
+        key: "x-stage"
+            value {string_value: "beta"}
+        }
+    };
+}
+```
+
+This is used in the C# SDK generator to warn about the stage of the
+endpoints
+
 ## Sending PRs
 
 Please take these general guidelines into consideration when you are sending a PR:

diff --git a/app/app/v1alpha/app_public_service.proto b/app/app/v1alpha/app_public_service.proto
@@ -48,15 +48,27 @@ service AppPublicService {
       post: "/v1alpha/namespaces/{namespace_id}/apps"
       body: "*"
     };
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 
   // List all apps info
   //
   // Returns a paginated list of apps.
   rpc ListApps(ListAppsRequest) returns (ListAppsResponse) {
     option (google.api.http) = {get: "/v1alpha/namespaces/{namespace_id}/apps"};
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 
   // Update a app info
@@ -67,15 +79,27 @@ service AppPublicService {
       put: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}"
       body: "*"
     };
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 
   // Delete a app
   //
   // Deletes an app.
   rpc DeleteApp(DeleteAppRequest) returns (DeleteAppResponse) {
     option (google.api.http) = {delete: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}"};
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 
   // Create a conversation
@@ -86,15 +110,27 @@ service AppPublicService {
       post: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations"
       body: "*"
     };
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 
   // List conversations
   //
   // Returns a paginated list of conversations.
   rpc ListConversations(ListConversationsRequest) returns (ListConversationsResponse) {
     option (google.api.http) = {get: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations"};
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 
   // Update a conversation
@@ -105,15 +141,27 @@ service AppPublicService {
       put: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations/{conversation_id}"
       body: "*"
     };
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 
   // Delete a conversation
   //
   // Deletes a conversation.
   rpc DeleteConversation(DeleteConversationRequest) returns (DeleteConversationResponse) {
     option (google.api.http) = {delete: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations/{conversation_id}"};
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 
   // Create a message
@@ -124,15 +172,27 @@ service AppPublicService {
       post: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations/{conversation_id}/messages"
       body: "*"
     };
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 
   // List messages
   //
   // Returns a paginated list of messages.
   rpc ListMessages(ListMessagesRequest) returns (ListMessagesResponse) {
     option (google.api.http) = {get: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations/{conversation_id}/messages"};
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 
   // Update a message
@@ -143,23 +203,41 @@ service AppPublicService {
       put: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations/{conversation_id}/messages/{message_uid}"
       body: "*"
     };
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 
   // Delete a message
   //
   // Deletes a message.
   rpc DeleteMessage(DeleteMessageRequest) returns (DeleteMessageResponse) {
     option (google.api.http) = {delete: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/conversations/{conversation_id}/messages/{message_uid}"};
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 
   // Get Playground Conversation
   //
   // Returns the latest conversation of auth user(e.g. login user and api key user).
   rpc GetPlaygroundConversation(GetPlaygroundConversationRequest) returns (GetPlaygroundConversationResponse) {
     option (google.api.http) = {get: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/ai_assistant_playground/conversation"};
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 
   // Restart Playground Conversation
@@ -168,7 +246,13 @@ service AppPublicService {
   // auto-generates a new conversation ID on the behalf of auth user.
   rpc RestartPlaygroundConversation(RestartPlaygroundConversationRequest) returns (RestartPlaygroundConversationResponse) {
     option (google.api.http) = {post: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/ai_assistant_playground/restart"};
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 
   // Chat
@@ -181,6 +265,12 @@ service AppPublicService {
       post: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/chat"
       body: "*"
     };
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "🍎 App"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      tags: "🍎 App"
+      extensions: {
+        key: "x-stage"
+        value: {string_value: "alpha"}
+      }
+    };
   }
 }