docs: improve English naturalness in API v2 documentation (calcom#22130)

* docs: improve English naturalness in API v2 documentation

- Fix awkward API summary 'Find out when is an event type ready to be booked' to 'Get available time slots for an event type'
- Correct 'setup' vs 'set up' usage throughout documentation
- Fix OAuth capitalization consistency
- Improve 'api' to 'API' capitalization in v2 docs
- Enhance readability while preserving technical accuracy

Fixes unnatural English phrasing in titles, headers, descriptions, and summaries across API v2 documentation files.

Co-Authored-By: keith@cal.com <keithwillcode@gmail.com>

* docs: add missing articles 'the' in API v2 documentation

- Fix 'How to Set Up API' to 'How to Set Up the API' in titles
- Add 'the' before 'API' in descriptions and summaries
- Fix grammar error 'all you need to is' to 'all you need to do is'
- Improve naturalness while maintaining technical accuracy

Co-Authored-By: keith@cal.com <keithwillcode@gmail.com>

* docs: fix unnatural English in API v2 @apioperation summaries

- Fix grammatically incorrect 'conferencing apps oauths callback' to 'Conferencing app OAuth callback'
- Replace 'ooo' with 'out-of-office' in user-facing summaries for clarity
- Ensure consistent sentence case capitalization (only first letter capitalized)
- Remove trailing periods from summaries for consistency
- Fix awkward phrasing like 'Get by attribute id all of...' to more natural English
- Revert 'Introduction to the API v2' back to 'Introduction to API v2'
- Improve naturalness while maintaining technical accuracy

Co-Authored-By: keith@cal.com <keithwillcode@gmail.com>

* Update apps/api/v2/src/modules/slots/slots-2024-09-04/controllers/slots.controller.ts

* Update docs/api-reference/v2/openapi.json

* docs: fix setup/set up usage - use 'backend setup' (noun) not 'backend set up' (verb)

Co-Authored-By: keith@cal.com <keithwillcode@gmail.com>

* docs: fix setup/set up verb usage - use 'set up' (verb) not 'setup' (verb)

- Fix 'You have to setup' → 'You have to set up' in quickstart.mdx
- Fix 'Setup environment variables' → 'Set up environment variables'
- Fix 'Setup root of your app' → 'Set up root of your app'
- Fix 'prompted to setup' → 'prompted to set up' in setup.mdx

Co-Authored-By: keith@cal.com <keithwillcode@gmail.com>

* Ran v2 locally to regen the doc json files

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: keithwillcode

apps/api/v2/src/ee/calendars/controllers/calendars.controller.ts

@@ -157,7 +157,7 @@ export class CalendarsController {
   @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
   @Get("/:calendar/connect")
   @HttpCode(HttpStatus.OK)
-  @ApiOperation({ summary: "Get oAuth connect URL" })
+  @ApiOperation({ summary: "Get OAuth connect URL" })
   @ApiQuery({
     name: "redir",
     required: false,

apps/api/v2/src/modules/conferencing/controllers/conferencing.controller.ts

@@ -87,7 +87,7 @@ export class ConferencingController {
   @HttpCode(HttpStatus.OK)
   @UseGuards(ApiAuthGuard)
   @ApiHeader(API_KEY_OR_ACCESS_TOKEN_HEADER)
-  @ApiOperation({ summary: "Get OAuth conferencing app auth url" })
+  @ApiOperation({ summary: "Get OAuth conferencing app auth URL" })
   @ApiParam({
     name: "app",
     description: "Conferencing application type",
@@ -130,7 +130,7 @@ export class ConferencingController {
   @Get("/:app/oauth/callback")
   @UseGuards()
   @Redirect(undefined, 301)
-  @ApiOperation({ summary: "conferencing apps oauths callback" })
+  @ApiOperation({ summary: "Conferencing app OAuth callback" })
   @ApiParam({
     name: "app",
     description: "Conferencing application type",

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

@@ -134,7 +134,7 @@ export class OrganizationsAttributesOptionsController {
   @Roles("ORG_MEMBER")
   @PlatformPlan("ESSENTIALS")
   @Get("/attributes/:attributeId/options/assigned")
-  @ApiOperation({ summary: "Get by attribute id all of the attribute options that are assigned to users" })
+  @ApiOperation({ summary: "Get all assigned attribute options by attribute ID" })
   async getOrganizationAttributeAssignedOptions(
     @Param("orgId", ParseIntPipe) orgId: number,
     @Param("attributeId") attributeId: string,
@@ -158,7 +158,7 @@ export class OrganizationsAttributesOptionsController {
   @Roles("ORG_MEMBER")
   @PlatformPlan("ESSENTIALS")
   @Get("/attributes/slugs/:attributeSlug/options/assigned")
-  @ApiOperation({ summary: "Get by attribute slug all of the attribute options that are assigned to users" })
+  @ApiOperation({ summary: "Get all assigned attribute options by attribute slug" })
   async getOrganizationAttributeAssignedOptionsBySlug(
     @Param("orgId", ParseIntPipe) orgId: number,
     @Param("attributeSlug") attributeSlug: string,

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

@@ -34,7 +34,7 @@ export class OrganizationsBookingsController {
   constructor(private readonly bookingsService: BookingsService_2024_08_13) {}
 
   @Get("/")
-  @ApiOperation({ summary: "Get Organization Bookings" })
+  @ApiOperation({ summary: "Get organization bookings" })
   @Roles("ORG_ADMIN")
   @PlatformPlan("ESSENTIALS")
   @HttpCode(HttpStatus.OK)

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

@@ -105,7 +105,7 @@ export class OrganizationsConferencingController {
   @UseGuards(ApiAuthGuard, IsOrgGuard, RolesGuard, IsTeamInOrg, PlatformPlanGuard, IsAdminAPIEnabledGuard)
   @Get("/teams/:teamId/conferencing/:app/oauth/auth-url")
   @HttpCode(HttpStatus.OK)
-  @ApiOperation({ summary: "Get OAuth conferencing app's auth url for a team" })
+  @ApiOperation({ summary: "Get OAuth conferencing app's auth URL for a team" })
   async getTeamOAuthUrl(
     @Req() req: Request,
     @Headers("Authorization") authorization: string,

apps/api/v2/src/modules/organizations/delegation-credentials/organizations-delegation-credential.controller.ts

@@ -52,7 +52,7 @@ export class OrganizationsDelegationCredentialController {
   @HttpCode(HttpStatus.CREATED)
   @Roles("ORG_ADMIN")
   @PlatformPlan("SCALE")
-  @ApiOperation({ summary: "Save delegation credentials for your organization." })
+  @ApiOperation({ summary: "Save delegation credentials for your organization" })
   async createDelegationCredential(
     @Param("orgId", ParseIntPipe) orgId: number,
     @GetUser() delegatedServiceAccountUser: User,
@@ -72,7 +72,7 @@ export class OrganizationsDelegationCredentialController {
   @Patch("/:credentialId")
   @Roles("ORG_ADMIN")
   @PlatformPlan("SCALE")
-  @ApiOperation({ summary: "Update delegation credentials of your organization." })
+  @ApiOperation({ summary: "Update delegation credentials of your organization" })
   async updateDelegationCredential(
     @Param("orgId", ParseIntPipe) orgId: number,
     @GetUser() delegatedServiceAccountUser: User,

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

@@ -65,7 +65,7 @@ export class OrganizationsStripeController {
   @UseGuards(ApiAuthGuard, IsOrgGuard, RolesGuard, IsTeamInOrg, PlatformPlanGuard, IsAdminAPIEnabledGuard)
   @Get("/connect")
   @HttpCode(HttpStatus.OK)
-  @ApiOperation({ summary: "Get stripe connect URL for a team" })
+  @ApiOperation({ summary: "Get Stripe connect URL for a team" })
   async getTeamStripeConnectUrl(
     @Req() req: Request,
     @Headers("Authorization") authorization: string,
@@ -104,7 +104,7 @@ export class OrganizationsStripeController {
   @UseGuards(ApiAuthGuard, IsOrgGuard, RolesGuard, IsTeamInOrg, PlatformPlanGuard, IsAdminAPIEnabledGuard)
   @Get("/check")
   @HttpCode(HttpStatus.OK)
-  @ApiOperation({ summary: "Check team stripe connection" })
+  @ApiOperation({ summary: "Check team Stripe connection" })
   async checkTeamStripeConnection(
     @Param("teamId", ParseIntPipe) teamId: number
   ): Promise<StripCredentialsCheckOutputResponseDto> {
@@ -116,7 +116,7 @@ export class OrganizationsStripeController {
   @UseGuards(ApiAuthGuard, IsOrgGuard, RolesGuard, IsTeamInOrg, PlatformPlanGuard, IsAdminAPIEnabledGuard)
   @Get("/save")
   @Redirect(undefined, 301)
-  @ApiOperation({ summary: "Save stripe credentials" })
+  @ApiOperation({ summary: "Save Stripe credentials" })
   async save(
     @Query("state") state: string,
     @Query("code") code: string,

apps/api/v2/src/modules/organizations/users/bookings/controllers/organizations-users-bookings-controller.ts

@@ -34,7 +34,7 @@ export class OrganizationsUsersBookingsController {
   @Get("/")
   @Roles("ORG_ADMIN")
   @PlatformPlan("ESSENTIALS")
-  @ApiOperation({ summary: "Get all bookings of an organization user" })
+  @ApiOperation({ summary: "Get all bookings for an organization user" })
   async getOrganizationUserBookings(
     @Param("orgId", ParseIntPipe) orgId: number,
     @Param("userId", ParseIntPipe) userId: number,

apps/api/v2/src/modules/organizations/users/ooo/controllers/organizations-users-ooo-controller.ts

@@ -66,7 +66,7 @@ export class OrganizationsUsersOOOController {
   @Roles("ORG_ADMIN")
   @PlatformPlan("ESSENTIALS")
   @UseGuards(IsUserInOrg)
-  @ApiOperation({ summary: "Get all ooo entries of a user" })
+  @ApiOperation({ summary: "Get all out-of-office entries for a user" })
   async getOrganizationUserOOO(
     @Param("userId", ParseIntPipe) userId: number,
     @Query() query: GetOutOfOfficeEntryFiltersDTO
@@ -84,7 +84,7 @@ export class OrganizationsUsersOOOController {
   @Roles("ORG_ADMIN")
   @PlatformPlan("ESSENTIALS")
   @UseGuards(IsUserInOrg)
-  @ApiOperation({ summary: "Create an ooo entry for user" })
+  @ApiOperation({ summary: "Create an out-of-office entry for a user" })
   async createOrganizationUserOOO(
     @Param("userId", ParseIntPipe) userId: number,
     @Body() input: CreateOutOfOfficeEntryDto
@@ -100,7 +100,7 @@ export class OrganizationsUsersOOOController {
   @Roles("ORG_ADMIN")
   @PlatformPlan("ESSENTIALS")
   @UseGuards(IsUserInOrg, IsUserOOO)
-  @ApiOperation({ summary: "Update ooo entry of a user" })
+  @ApiOperation({ summary: "Update an out-of-office entry for a user" })
   async updateOrganizationUserOOO(
     @Param("userId", ParseIntPipe) userId: number,
     @Param("oooId", ParseIntPipe) oooId: number,
@@ -118,7 +118,7 @@ export class OrganizationsUsersOOOController {
   @Roles("ORG_ADMIN")
   @PlatformPlan("ESSENTIALS")
   @UseGuards(IsUserInOrg, IsUserOOO)
-  @ApiOperation({ summary: "Delete ooo entry of a user" })
+  @ApiOperation({ summary: "Delete an out-of-office entry for a user" })
   async deleteOrganizationUserOOO(
     @Param("oooId", ParseIntPipe) oooId: number
   ): Promise<UserOooOutputResponseDto> {
@@ -132,7 +132,7 @@ export class OrganizationsUsersOOOController {
   @Get("/ooo")
   @Roles("ORG_ADMIN")
   @PlatformPlan("ESSENTIALS")
-  @ApiOperation({ summary: "Get all OOO entries of org users" })
+  @ApiOperation({ summary: "Get all out-of-office entries for organization users" })
   async getOrganizationUsersOOO(
     @Param("orgId", ParseIntPipe) orgId: number,
     @Query() query: GetOrgUsersOutOfOfficeEntryFiltersDTO

apps/api/v2/src/modules/slots/slots-2024-09-04/controllers/slots.controller.ts

@@ -58,7 +58,7 @@ export class SlotsController_2024_09_04 {
 
   @Get("/")
   @ApiOperation({
-    summary: "Find out when is an event type ready to be booked.",
+    summary: "Get available time slots for an event type",
     description: `
       There are 4 ways to get available slots for event type of an individual user:
 
@@ -290,7 +290,7 @@ export class SlotsController_2024_09_04 {
 
   @Patch("/reservations/:uid")
   @ApiOperation({
-    summary: "Updated reserved a slot",
+    summary: "Update a reserved slot",
   })
   @HttpCode(HttpStatus.OK)
   async updateReservedSlot(