fix(openapi): add missing tags to OpenAPI definitions (#459)

Because - Some endpoints reference tags that aren't defined at the root of the OpenAPI docs. This commit - Adds missing tags. --------- Co-authored-by: droplet-bot <[email protected]>
instill-ai · Sep 20, 2024 · e0d4056 · e0d4056
1 parent 35cfcdf
commit e0d4056
Show file tree

Hide file tree

Showing 10 changed files with 76 additions and 22 deletions.
diff --git a/app/app/v1alpha/app_public_service.proto b/app/app/v1alpha/app_public_service.proto
@@ -76,58 +76,58 @@ 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"};
   }
   // List 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"};
   }
   // Update a conversation
   rpc UpdateConversation(UpdateConversationRequest) returns (UpdateConversationResponse) {
     option (google.api.http) = {
       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"};
   }
   // Delete 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"};
   }
   // Create a message
   rpc CreateMessage(CreateMessageRequest) returns (CreateMessageResponse) {
     option (google.api.http) = {
       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"};
   }
   // List 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"};
   }
   // Update a message
   rpc UpdateMessage(UpdateMessageRequest) returns (UpdateMessageResponse) {
     option (google.api.http) = {
       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"};
   }
   // Delete 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"};
   }
   // Update ai assistant app playground
   rpc UpdateAiAssistantAppPlayground(UpdateAiAssistantAppPlaygroundRequest) returns (UpdateAiAssistantAppPlaygroundResponse) {
     option (google.api.http) = {
       put: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/ai_assistant_playground"
       body: "*"
     };
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "app"};
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {tags: "App"};
   }
 }
diff --git a/app/app/v1alpha/openapi.proto.templ b/app/app/v1alpha/openapi.proto.templ
@@ -11,6 +11,11 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
     description: "App endpoints to manage app resources"
 {{$info}}
   }
-  tags: []
+  tags: [
+    {
+      name: "App"
+      description: "App endpoints"
+    }
+  ]
 {{$conf}}
 };
diff --git a/artifact/artifact/v1alpha/artifact_public_service.proto b/artifact/artifact/v1alpha/artifact_public_service.proto
@@ -42,6 +42,8 @@ service ArtifactPublicService {
     option (google.api.method_visibility).restriction = "INTERNAL";
   }
 
+  // TODO improve public endpoint definitions with title and description.
+
   // Create a catalog
   rpc CreateCatalog(CreateCatalogRequest) returns (CreateCatalogResponse) {
     option (google.api.http) = {

diff --git a/artifact/artifact/v1alpha/openapi.proto.templ b/artifact/artifact/v1alpha/openapi.proto.templ
@@ -8,9 +8,14 @@ import "protoc-gen-openapiv2/options/annotations.proto";
 option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
   info: {
     title: "💾 Artifact "
-    description: "Artifact endpoints to manage artifact resources"
+    description: "Artifact endpoints to manage Instill Catalog and RAG applications",
 {{$info}}
   }
-  tags: []
+  tags: [
+    {
+      name: "Catalog"
+      description: "Catalog endpoints"
+    }
+  ]
 {{$conf}}
 };
diff --git a/model/model/v1alpha/openapi.proto.templ b/model/model/v1alpha/openapi.proto.templ
@@ -28,6 +28,18 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
       name: "Trigger"
       description: "Model trigger endpoints"
     },
+    {
+      name: "Model (Deprecated)"
+      description: "Deprecated model endpoints"
+    },
+    {
+      name: "Version (Deprecated)"
+      description: "Deprecated version endpoints"
+    },
+    {
+      name: "Trigger (Deprecated)"
+      description: "Deprecated trigger endpoints"
+    },
     {
       name: "Region"
       description: "Model region endpoints"

diff --git a/openapiv2/app/service.swagger.yaml b/openapiv2/app/service.swagger.yaml
@@ -10,6 +10,9 @@ info:
   license:
     name: Elastic License 2.0 (ELv2)
     url: https://github.com/instill-ai/protobufs/blob/main/LICENSE
+tags:
+  - name: App
+    description: App endpoints
 host: api.instill.tech
 schemes:
   - https
@@ -182,7 +185,7 @@ paths:
           required: false
           type: boolean
       tags:
-        - app
+        - App
     post:
       summary: Create a Conversation
       operationId: AppPublicService_CreateConversation
@@ -215,7 +218,7 @@ paths:
           schema:
             $ref: '#/definitions/AppPublicServiceCreateConversationBody'
       tags:
-        - app
+        - App
   /v1alpha/namespaces/{namespaceId}/apps/{appId}/conversations/{conversationId}:
     delete:
       summary: Delete a conversation
@@ -249,7 +252,7 @@ paths:
           required: true
           type: string
       tags:
-        - app
+        - App
     put:
       summary: Update a conversation
       operationId: AppPublicService_UpdateConversation
@@ -287,7 +290,7 @@ paths:
           schema:
             $ref: '#/definitions/AppPublicServiceUpdateConversationBody'
       tags:
-        - app
+        - App
   /v1alpha/namespaces/{namespaceId}/apps/{appId}/conversations/{conversationId}/messages:
     get:
       summary: List messages
@@ -348,7 +351,7 @@ paths:
           required: false
           type: boolean
       tags:
-        - app
+        - App
     post:
       summary: Create a message
       operationId: AppPublicService_CreateMessage
@@ -386,7 +389,7 @@ paths:
           schema:
             $ref: '#/definitions/AppPublicServiceCreateMessageBody'
       tags:
-        - app
+        - App
   /v1alpha/namespaces/{namespaceId}/apps/{appId}/conversations/{conversationId}/messages/{messageUid}:
     delete:
       summary: Delete a message
@@ -425,7 +428,7 @@ paths:
           required: true
           type: string
       tags:
-        - app
+        - App
     put:
       summary: Update a message
       operationId: AppPublicService_UpdateMessage
@@ -468,7 +471,7 @@ paths:
           schema:
             $ref: '#/definitions/AppPublicServiceUpdateMessageBody'
       tags:
-        - app
+        - App
   /v1alpha/namespaces/{namespaceId}/apps/{appId}/ai_assistant_playground:
     put:
       summary: Update ai assistant app playground
@@ -502,7 +505,7 @@ paths:
           schema:
             $ref: '#/definitions/AppPublicServiceUpdateAiAssistantAppPlaygroundBody'
       tags:
-        - app
+        - App
 definitions:
   AppPublicServiceCreateAppBody:
     type: object

diff --git a/openapiv2/artifact/service.swagger.yaml b/openapiv2/artifact/service.swagger.yaml
@@ -1,7 +1,7 @@
 swagger: "2.0"
 info:
   title: "\U0001F4BE Artifact "
-  description: Artifact endpoints to manage artifact resources
+  description: Artifact endpoints to manage Instill Catalog and RAG applications
   version: v0.40.1-beta
   contact:
     name: Instill AI
@@ -10,6 +10,9 @@ info:
   license:
     name: Elastic License 2.0 (ELv2)
     url: https://github.com/instill-ai/protobufs/blob/main/LICENSE
+tags:
+  - name: Catalog
+    description: Catalog endpoints
 host: api.instill.tech
 schemes:
   - https

diff --git a/openapiv2/model/service.swagger.yaml b/openapiv2/model/service.swagger.yaml
@@ -19,6 +19,12 @@ tags:
     description: Model version endpoints
   - name: Trigger
     description: Model trigger endpoints
+  - name: Model (Deprecated)
+    description: Deprecated model endpoints
+  - name: Version (Deprecated)
+    description: Deprecated version endpoints
+  - name: Trigger (Deprecated)
+    description: Deprecated trigger endpoints
   - name: Region
     description: Model region endpoints
 host: api.instill.tech

diff --git a/openapiv2/vdp/service.swagger.yaml b/openapiv2/vdp/service.swagger.yaml
@@ -23,6 +23,12 @@ tags:
     description: Namespace Secret endpoints
   - name: Integration
     description: Namespace Integration endpoints
+  - name: Pipeline (Deprecated)
+    description: Deprecated pipeline endpoints
+  - name: Trigger (Deprecated)
+    description: Deprecated trigger endpoints
+  - name: Release (Deprecated)
+    description: Deprecated release endpoints
   - name: Utils
     description: Utils endpoints
 host: api.instill.tech

diff --git a/vdp/pipeline/v1beta/openapi.proto.templ b/vdp/pipeline/v1beta/openapi.proto.templ
@@ -36,6 +36,18 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
         name: "Integration"
         description: "Namespace Integration endpoints"
     },
+    {
+      name: "Pipeline (Deprecated)"
+      description: "Deprecated pipeline endpoints"
+    },
+    {
+      name: "Trigger (Deprecated)"
+      description: "Deprecated trigger endpoints"
+    },
+    {
+      name: "Release (Deprecated)"
+      description: "Deprecated release endpoints"
+    },
     {
       name: "Utils"
       description: "Utils endpoints"