chore: add docs to /v2/organizations/:orgId/organizations endpoints (#19668)

Co-authored-by: Somay Chauhan <somaychauhan98@gmail.com>

apps/api/v2/src/modules/organizations/organizations/organizations-organizations.controller.ts

@@ -46,7 +46,11 @@ export class OrganizationsOrganizationsController {
   @Post()
   @Roles("ORG_ADMIN")
   @PlatformPlan(SCALE)
-  @ApiOperation({ summary: "Create an organization within an organization" })
+  @ApiOperation({
+    summary: "Create an organization within an organization",
+    description:
+      "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
+  })
   async createOrganization(
     @Param("orgId", ParseIntPipe) managerOrganizationId: number,
     @GetUser() authUser: ApiAuthGuardUser,
@@ -67,7 +71,11 @@ export class OrganizationsOrganizationsController {
   @Roles("ORG_ADMIN")
   @PlatformPlan(SCALE)
   @Get("/:managedOrganizationId")
-  @ApiOperation({ summary: "Get an organization within an organization" })
+  @ApiOperation({
+    summary: "Get an organization within an organization",
+    description:
+      "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
+  })
   @UseGuards(IsManagedOrgInManagerOrg)
   async getOrganization(
     @Param("managedOrganizationId", ParseIntPipe) managedOrganizationId: number
@@ -82,7 +90,11 @@ export class OrganizationsOrganizationsController {
   @Roles("ORG_ADMIN")
   @PlatformPlan(SCALE)
   @Get("/")
-  @ApiOperation({ summary: "Get all organizations within an organization" })
+  @ApiOperation({
+    summary: "Get all organizations within an organization",
+    description:
+      "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
+  })
   async getOrganizations(
     @Param("orgId", ParseIntPipe) managerOrganizationId: number
   ): Promise<GetManagedOrganizationsOutput> {
@@ -98,7 +110,11 @@ export class OrganizationsOrganizationsController {
   @Roles("ORG_ADMIN")
   @PlatformPlan(SCALE)
   @Patch("/:managedOrganizationId")
-  @ApiOperation({ summary: "Update an organization within an organization" })
+  @ApiOperation({
+    summary: "Update an organization within an organization",
+    description:
+      "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
+  })
   @UseGuards(IsManagedOrgInManagerOrg)
   @HttpCode(HttpStatus.OK)
   async updateOrganization(
@@ -119,7 +135,11 @@ export class OrganizationsOrganizationsController {
   @Roles("ORG_ADMIN")
   @PlatformPlan(SCALE)
   @Delete("/:managedOrganizationId")
-  @ApiOperation({ summary: "Delete an organization within an organization" })
+  @ApiOperation({
+    summary: "Delete an organization within an organization",
+    description:
+      "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
+  })
   @UseGuards(IsManagedOrgInManagerOrg)
   async deleteOrganization(
     @Param("managedOrganizationId", ParseIntPipe) managedOrganizationId: number

apps/api/v2/swagger/documentation.json

@@ -1717,6 +1717,7 @@
       "post": {
         "operationId": "OrganizationsOrganizationsController_createOrganization",
         "summary": "Create an organization within an organization",
+        "description": "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
         "parameters": [
           {
             "name": "orgId",
@@ -1756,6 +1757,7 @@
       "get": {
         "operationId": "OrganizationsOrganizationsController_getOrganizations",
         "summary": "Get all organizations within an organization",
+        "description": "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
         "parameters": [
           {
             "name": "orgId",
@@ -1787,6 +1789,7 @@
       "get": {
         "operationId": "OrganizationsOrganizationsController_getOrganization",
         "summary": "Get an organization within an organization",
+        "description": "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
         "parameters": [
           {
             "name": "managedOrganizationId",
@@ -1816,6 +1819,7 @@
       "patch": {
         "operationId": "OrganizationsOrganizationsController_updateOrganization",
         "summary": "Update an organization within an organization",
+        "description": "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
         "parameters": [
           {
             "name": "orgId",
@@ -1863,6 +1867,7 @@
       "delete": {
         "operationId": "OrganizationsOrganizationsController_deleteOrganization",
         "summary": "Delete an organization within an organization",
+        "description": "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
         "parameters": [
           {
             "name": "managedOrganizationId",

docs/api-reference/v2/openapi.json

@@ -1635,6 +1635,7 @@
       "post": {
         "operationId": "OrganizationsOrganizationsController_createOrganization",
         "summary": "Create an organization within an organization",
+        "description": "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
         "parameters": [
           {
             "name": "orgId",
@@ -1672,6 +1673,7 @@
       "get": {
         "operationId": "OrganizationsOrganizationsController_getOrganizations",
         "summary": "Get all organizations within an organization",
+        "description": "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
         "parameters": [
           {
             "name": "orgId",
@@ -1701,6 +1703,7 @@
       "get": {
         "operationId": "OrganizationsOrganizationsController_getOrganization",
         "summary": "Get an organization within an organization",
+        "description": "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
         "parameters": [
           {
             "name": "managedOrganizationId",
@@ -1728,6 +1731,7 @@
       "patch": {
         "operationId": "OrganizationsOrganizationsController_updateOrganization",
         "summary": "Update an organization within an organization",
+        "description": "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
         "parameters": [
           {
             "name": "orgId",
@@ -1773,6 +1777,7 @@
       "delete": {
         "operationId": "OrganizationsOrganizationsController_deleteOrganization",
         "summary": "Delete an organization within an organization",
+        "description": "Requires the user to have at least the 'ORG_ADMIN' role within the organization. Additionally, for platform, the plan must be 'SCALE' or higher to access this endpoint.",
         "parameters": [
           {
             "name": "managedOrganizationId",