docs(openapi): Align new endpoints with existing ones

model/model/v1alpha/model_public_service.proto

@@ -262,7 +262,7 @@ service ModelPublicService {
 
   // Create a new model
   //
-  // Creates a new model under the parenthood of a organization. This is an
+  // Creates a new model under the parenthood of an organization. This is an
   // asynchronous endpoint, i.e., the server will not wait for the model to be
   // created in order to respond. Instead, it will return a response with the
   // necessary information to access the result and status of the creation

openapiv2/model/service.swagger.yaml

@@ -826,7 +826,7 @@ paths:
     post:
       summary: Create a new model
       description: |-
-        Creates a new model under the parenthood of a organization. This is an
+        Creates a new model under the parenthood of an organization. This is an
         asynchronous endpoint, i.e., the server will not wait for the model to be
         created in order to respond. Instead, it will return a response with the
         necessary information to access the result and status of the creation

openapiv2/vdp/service.swagger.yaml

@@ -535,7 +535,9 @@ paths:
   /v1beta/{user_pipeline_name}/clone:
     post:
       summary: Clone a pipeline owned by a user
-      description: Clone a pipeline owned by a user, the target pipeline can be under a user or organization namespace.
+      description: |-
+        Clones a pipeline owned by a user. The new pipeline may have a different
+        parent, and this can be either a user or an organization.
       operationId: PipelinePublicService_CloneUserPipeline
       responses:
         "200":
@@ -1508,7 +1510,9 @@ paths:
   /v1beta/{user_pipeline_name_1}/clone:
     post:
       summary: Clone a pipeline owned by an organization
-      description: Clone a pipeline owned by an organization, the target pipeline can be under a user or organization namespace.
+      description: |-
+        Clones a pipeline owned by an organization. The new pipeline may have a
+        different parent, and this can be either a user or an organization.
       operationId: PipelinePublicService_CloneOrganizationPipeline
       responses:
         "200":
@@ -1525,9 +1529,9 @@ paths:
       parameters:
         - name: user_pipeline_name_1
           description: |-
-            The resource name of the pipeline, which allows its access by parent user
-            and ID.
-            - Format: `organizations/{org.id}/pipelines/{pipeline.id}`.
+            The resource name of the pipeline, which allows its access by parent
+            organization and ID.
+            - Format: `organizations/{organization.id}/pipelines/{pipeline.id}`.
           in: path
           required: true
           type: string
@@ -3393,11 +3397,8 @@ paths:
     post:
       summary: Check the availibity of a resource name
       description: |-
-        Check the availibity of a resource name. The name should be in the formats:
-         - users/<user_id>/pipelines/<pipeline_id>
-         - users/<user_id>/connectors/<connector_id>
-         - organizations/<org_id>/pipelines/<pipeline_id>
-         - organizations/<org_id>/connectors/<connector_id>
+        Check whether a resource name is already in use. Currently this endpoint
+        only supports pipeline and connector resource names.
       operationId: PipelinePublicService_CheckName
       responses:
         "200":
@@ -3429,9 +3430,10 @@ definitions:
       - NAME_AVAILABLE
       - NAME_UNAVAILABLE
     description: |-
-      - NAME_AVAILABLE: Available.
+      Name defines the availability of a resource name.
+
+       - NAME_AVAILABLE: Available.
        - NAME_UNAVAILABLE: Unavailable.
-    title: Availability of Name
   HealthCheckResponseServingStatus:
     type: string
     enum:
@@ -3447,9 +3449,13 @@ definitions:
       target:
         type: string
         title: |-
-          The target pipeline
-          - Format: `users/{user.id}/pipelines/{pipeline.id}` or `organizations/{org.id}/pipelines/{pipeline.id}`
-    description: CloneOrganizationPipelineRequest represents a request to clone a pipeline owned by a organization.
+          The target pipeline name. It can be under a user or an organization
+          namespace, so the following formats are accepted:
+          - `users/{user.id}/pipelines/{pipeline.id}`
+          - `organizations/{organization.id}/pipelines/{pipeline.id}`
+    description: |-
+      CloneOrganizationPipelineRequest represents a request to clone a pipeline
+      owned by an organization.
     required:
       - target
   PipelinePublicServiceCloneUserPipelineBody:
@@ -3458,9 +3464,13 @@ definitions:
       target:
         type: string
         title: |-
-          The target pipeline
-          - Format: `users/{user.id}/pipelines/{pipeline.id}` or `organizations/{org.id}/pipelines/{pipeline.id}`
-    description: CloneUserPipelineRequest represents a request to clone a pipeline owned by a user.
+          The target pipeline name. It can be under a user or an organization
+          namespace, so the following formats are accepted:
+          - `users/{user.id}/pipelines/{pipeline.id}`
+          - `organizations/{organization.id}/pipelines/{pipeline.id}`
+    description: |-
+      CloneUserPipelineRequest represents a request to clone a pipeline owned by a
+      user.
     required:
       - target
   PipelinePublicServiceConnectOrganizationConnectorBody:
@@ -3957,11 +3967,12 @@ definitions:
       name:
         type: string
         title: |-
-          The name of the resource to be checked, should be in the formats:
-           - users/<user_id>/pipelines/<pipeline_id>
-           - users/<user_id>/connectors/<connector_id>
-           - organizations/<org_id>/pipelines/<pipeline_id>
-           - organizations/<org_id>/connectors/<connector_id>
+          The name of the resource to be checked. For the moment, only pipeline and
+          connector names can be checked. The following formats are accepted:
+          - `users/{user.id}/pipelines/{pipeline.id}`
+          - `users/{user.id}/connectors/{connector.id}`
+          - `organizations/{organization.id}/pipelines/{pipeline.id}`
+          - `organizations/{organization.id}/connectors/{connector.id}`
     description: |-
       CheckNameRequest represents a request to verify if a name is
       available.
@@ -3972,10 +3983,8 @@ definitions:
     properties:
       availability:
         $ref: '#/definitions/CheckNameResponseName'
-        title: Availability
-    description: |-
-      CheckNameResponse contains the availability of a name
-      of resource that's using it.
+        description: The availability of the requested name.
+    description: CheckNameResponse contains the availability of a resource name.
   v1betaCloneOrganizationPipelineResponse:
     type: object
     properties:

vdp/pipeline/v1beta/common.proto

@@ -66,18 +66,18 @@ message Permission {
 // CheckNameRequest represents a request to verify if a name is
 // available.
 message CheckNameRequest {
-  // The name of the resource to be checked, should be in the formats:
-  //  - users/<user_id>/pipelines/<pipeline_id>
-  //  - users/<user_id>/connectors/<connector_id>
-  //  - organizations/<org_id>/pipelines/<pipeline_id>
-  //  - organizations/<org_id>/connectors/<connector_id>
+  // The name of the resource to be checked. For the moment, only pipeline and
+  // connector names can be checked. The following formats are accepted:
+  // - `users/{user.id}/pipelines/{pipeline.id}`
+  // - `users/{user.id}/connectors/{connector.id}`
+  // - `organizations/{organization.id}/pipelines/{pipeline.id}`
+  // - `organizations/{organization.id}/connectors/{connector.id}`
   string name = 1 [(google.api.field_behavior) = REQUIRED];
 }
 
-// CheckNameResponse contains the availability of a name
-// of resource that's using it.
+// CheckNameResponse contains the availability of a resource name.
 message CheckNameResponse {
-  // Availability of Name
+  // Name defines the availability of a resource name.
   enum Name {
     // Unspecified.
     NAME_UNSPECIFIED = 0;
@@ -87,6 +87,6 @@ message CheckNameResponse {
     NAME_UNAVAILABLE = 2;
   }
 
-  // Availability
+  // The availability of the requested name.
   Name availability = 1;
 }

vdp/pipeline/v1beta/connector.proto

@@ -437,7 +437,7 @@ message CreateOrganizationConnectorResponse {
 }
 
 // ListOrganizationConnectorsRequest represents a request to list the
-// connectors of a organization.
+// connectors of an organization.
 message ListOrganizationConnectorsRequest {
   // The maximum number of connectors to return. If this parameter is
   // unspecified, at most 10 connectors will be returned. The cap value for this
@@ -644,7 +644,7 @@ message TestOrganizationConnectorResponse {
 }
 
 // WatchOrganizationConnectorRequest represents a request to fetch the state of
-// a organization-owned connector.
+// an organization-owned connector.
 message WatchOrganizationConnectorRequest {
   // The resource name of the connector, which allows its access by parent
   // connector and ID.

vdp/pipeline/v1beta/pipeline.proto

@@ -478,7 +478,8 @@ message RenameUserPipelineResponse {
   Pipeline pipeline = 1;
 }
 
-// CloneUserPipelineRequest represents a request to clone a pipeline owned by a user.
+// CloneUserPipelineRequest represents a request to clone a pipeline owned by a
+// user.
 message CloneUserPipelineRequest {
   // The resource name of the pipeline, which allows its access by parent user
   // and ID.
@@ -490,8 +491,10 @@ message CloneUserPipelineRequest {
       field_configuration: {path_param_name: "user_pipeline_name"}
     }
   ];
-  // The target pipeline
-  // - Format: `users/{user.id}/pipelines/{pipeline.id}` or `organizations/{org.id}/pipelines/{pipeline.id}`
+  // The target pipeline name. It can be under a user or an organization
+  // namespace, so the following formats are accepted:
+  // - `users/{user.id}/pipelines/{pipeline.id}`
+  // - `organizations/{organization.id}/pipelines/{pipeline.id}`
   string target = 2 [(google.api.field_behavior) = REQUIRED];
 }
 
@@ -811,7 +814,7 @@ message CreateOrganizationPipelineResponse {
 }
 
 // ListOrganizationPipelinesRequest represents a request to list the pipelines
-// of a organization.
+// of an organization.
 message ListOrganizationPipelinesRequest {
   // The maximum number of pipelines to return. If this parameter is
   // unspecified, at most 10 pipelines will be returned. The cap value for this
@@ -956,20 +959,23 @@ message RenameOrganizationPipelineResponse {
   Pipeline pipeline = 1;
 }
 
-// CloneOrganizationPipelineRequest represents a request to clone a pipeline owned by a organization.
+// CloneOrganizationPipelineRequest represents a request to clone a pipeline
+// owned by an organization.
 message CloneOrganizationPipelineRequest {
-  // The resource name of the pipeline, which allows its access by parent user
-  // and ID.
-  // - Format: `organizations/{org.id}/pipelines/{pipeline.id}`.
+  // The resource name of the pipeline, which allows its access by parent
+  // organization and ID.
+  // - Format: `organizations/{organization.id}/pipelines/{pipeline.id}`.
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {type: "api.instill.tech/Pipeline"},
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       field_configuration: {path_param_name: "user_pipeline_name"}
     }
   ];
-  // The target pipeline
-  // - Format: `users/{user.id}/pipelines/{pipeline.id}` or `organizations/{org.id}/pipelines/{pipeline.id}`
+  // The target pipeline name. It can be under a user or an organization
+  // namespace, so the following formats are accepted:
+  // - `users/{user.id}/pipelines/{pipeline.id}`
+  // - `organizations/{organization.id}/pipelines/{pipeline.id}`
   string target = 2 [(google.api.field_behavior) = REQUIRED];
 }
 
@@ -1201,7 +1207,7 @@ message RenameOrganizationPipelineReleaseResponse {
 }
 
 // WatchOrganizationPipelineReleaseRequest represents a request to query the
-// state of a organization-owned pipeline release.
+// state of an organization-owned pipeline release.
 message WatchOrganizationPipelineReleaseRequest {
   // The resource name of the pipeline release, which allows its access by
   // parent pipeline and ID.

vdp/pipeline/v1beta/pipeline_public_service.proto

@@ -152,7 +152,8 @@ service PipelinePublicService {
 
   // Clone a pipeline owned by a user
   //
-  // Clone a pipeline owned by a user, the target pipeline can be under a user or organization namespace.
+  // Clones a pipeline owned by a user. The new pipeline may have a different
+  // parent, and this can be either a user or an organization.
   rpc CloneUserPipeline(CloneUserPipelineRequest) returns (CloneUserPipelineResponse) {
     option (google.api.http) = {
       post: "/v1beta/{name=users/*/pipelines/*}/clone"
@@ -422,7 +423,8 @@ service PipelinePublicService {
 
   // Clone a pipeline owned by an organization
   //
-  // Clone a pipeline owned by an organization, the target pipeline can be under a user or organization namespace.
+  // Clones a pipeline owned by an organization. The new pipeline may have a
+  // different parent, and this can be either a user or an organization.
   rpc CloneOrganizationPipeline(CloneOrganizationPipelineRequest) returns (CloneOrganizationPipelineResponse) {
     option (google.api.http) = {
       post: "/v1beta/{name=organizations/*/pipelines/*}/clone"
@@ -896,11 +898,8 @@ service PipelinePublicService {
 
   // Check the availibity of a resource name
   //
-  // Check the availibity of a resource name. The name should be in the formats:
-  //  - users/<user_id>/pipelines/<pipeline_id>
-  //  - users/<user_id>/connectors/<connector_id>
-  //  - organizations/<org_id>/pipelines/<pipeline_id>
-  //  - organizations/<org_id>/connectors/<connector_id>
+  // Check whether a resource name is already in use. Currently this endpoint
+  // only supports pipeline and connector resource names.
   rpc CheckName(CheckNameRequest) returns (CheckNameResponse) {
     option (google.api.http) = {
       post: "/v1beta/check-name"