vynte-infra/calendar
2
0
Fork 0
Code Issues Pull Requests Actions 2.0k Packages Projects Releases Wiki Activity

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

Browse Source 
* 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>
This commit is contained in:
Keith Williams
2025-07-03 23:47:09 +00:00
committed by GitHub
co-authored by keith@cal.com <keithwillcode@gmail.com> Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
parent 850ac8092f
commit 739ef153f6
22 changed files with 100 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api-reference/v2/openapi.json
+24 -24
View File
@@ -1123,7 +1123,7 @@
"/v2/organizations/{orgId}/attributes/{attributeId}/options/assigned": {
"get": {
"operationId": "OrganizationsAttributesOptionsController_getOrganizationAttributeAssignedOptions",
"summary": "Get by attribute id all of the attribute options that are assigned to users",
"summary": "Get all assigned attribute options by attribute ID",
"parameters": [
{
"name": "Authorization",
@@ -1215,7 +1215,7 @@
"/v2/organizations/{orgId}/attributes/slugs/{attributeSlug}/options/assigned": {
"get": {
"operationId": "OrganizationsAttributesOptionsController_getOrganizationAttributeAssignedOptionsBySlug",
"summary": "Get by attribute slug all of the attribute options that are assigned to users",
"summary": "Get all assigned attribute options by attribute slug",
"parameters": [
{
"name": "Authorization",
@@ -1467,7 +1467,7 @@
"/v2/organizations/{orgId}/bookings": {
"get": {
"operationId": "OrganizationsBookingsController_getAllOrgTeamBookings",
"summary": "Get Organization Bookings",
"summary": "Get organization bookings",
"parameters": [
{
"name": "Authorization",
@@ -1763,7 +1763,7 @@
"/v2/organizations/{orgId}/delegation-credentials": {
"post": {
"operationId": "OrganizationsDelegationCredentialController_createDelegationCredential",
"summary": "Save delegation credentials for your organization.",
"summary": "Save delegation credentials for your organization",
"parameters": [
{
"name": "Authorization",
@@ -1831,7 +1831,7 @@
"/v2/organizations/{orgId}/delegation-credentials/{credentialId}": {
"patch": {
"operationId": "OrganizationsDelegationCredentialController_updateDelegationCredential",
"summary": "Update delegation credentials of your organization.",
"summary": "Update delegation credentials of your organization",
"parameters": [
{
"name": "Authorization",
@@ -3454,7 +3454,7 @@
"/v2/organizations/{orgId}/teams/{teamId}/conferencing/{app}/oauth/auth-url": {
"get": {
"operationId": "OrganizationsConferencingController_getTeamOAuthUrl",
"summary": "Get OAuth conferencing app's auth url for a team",
"summary": "Get OAuth conferencing app's auth URL for a team",
"parameters": [
{
"name": "Authorization",
@@ -5761,7 +5761,7 @@
"/v2/organizations/{orgId}/users/{userId}/bookings": {
"get": {
"operationId": "OrganizationsUsersBookingsController_getOrganizationUserBookings",
"summary": "Get all bookings of an organization user",
"summary": "Get all bookings for an organization user",
"parameters": [
{
"name": "Authorization",
@@ -6048,7 +6048,7 @@
"/v2/organizations/{orgId}/users/{userId}/ooo": {
"get": {
"operationId": "OrganizationsUsersOOOController_getOrganizationUserOOO",
"summary": "Get all ooo entries of a user",
"summary": "Get all out-of-office entries for a user",
"parameters": [
{
"name": "Authorization",
@@ -6150,7 +6150,7 @@
},
"post": {
"operationId": "OrganizationsUsersOOOController_createOrganizationUserOOO",
"summary": "Create an ooo entry for user",
"summary": "Create an out-of-office entry for a user",
"parameters": [
{
"name": "Authorization",
@@ -6211,7 +6211,7 @@
"/v2/organizations/{orgId}/users/{userId}/ooo/{oooId}": {
"patch": {
"operationId": "OrganizationsUsersOOOController_updateOrganizationUserOOO",
"summary": "Update ooo entry of a user",
"summary": "Update an out-of-office entry for a user",
"parameters": [
{
"name": "Authorization",
@@ -6278,7 +6278,7 @@
},
"delete": {
"operationId": "OrganizationsUsersOOOController_deleteOrganizationUserOOO",
"summary": "Delete ooo entry of a user",
"summary": "Delete an out-of-office entry for a user",
"parameters": [
{
"name": "Authorization",
@@ -6329,7 +6329,7 @@
"/v2/organizations/{orgId}/ooo": {
"get": {
"operationId": "OrganizationsUsersOOOController_getOrganizationUsersOOO",
"summary": "Get all OOO entries of org users",
"summary": "Get all out-of-office entries for organization users",
"parameters": [
{
"name": "Authorization",
@@ -8362,7 +8362,7 @@
"/v2/calendars/{calendar}/connect": {
"get": {
"operationId": "CalendarsController_redirect",
"summary": "Get oAuth connect URL",
"summary": "Get OAuth connect URL",
"parameters": [
{
"name": "Authorization",
@@ -8657,7 +8657,7 @@
"/v2/conferencing/{app}/oauth/auth-url": {
"get": {
"operationId": "ConferencingController_redirect",
"summary": "Get OAuth conferencing app auth url",
"summary": "Get OAuth conferencing app auth URL",
"parameters": [
{
"name": "Authorization",
@@ -8718,7 +8718,7 @@
"/v2/conferencing/{app}/oauth/callback": {
"get": {
"operationId": "ConferencingController_save",
"summary": "conferencing apps oauths callback",
"summary": "Conferencing app OAuth callback",
"parameters": [
{
"name": "state",
@@ -10488,7 +10488,7 @@
"/v2/organizations/{orgId}/teams/{teamId}/stripe/connect": {
"get": {
"operationId": "OrganizationsStripeController_getTeamStripeConnectUrl",
"summary": "Get stripe connect URL for a team",
"summary": "Get Stripe connect URL for a team",
"parameters": [
{
"name": "Authorization",
@@ -10551,7 +10551,7 @@
"/v2/organizations/{orgId}/teams/{teamId}/stripe/check": {
"get": {
"operationId": "OrganizationsStripeController_checkTeamStripeConnection",
"summary": "Check team stripe connection",
"summary": "Check team Stripe connection",
"parameters": [
{
"name": "teamId",
@@ -10582,7 +10582,7 @@
"/v2/organizations/{orgId}/teams/{teamId}/stripe/save": {
"get": {
"operationId": "OrganizationsStripeController_save",
"summary": "Save stripe credentials",
"summary": "Save Stripe credentials",
"parameters": [
{
"name": "state",
@@ -11131,7 +11131,7 @@
"/v2/slots": {
"get": {
"operationId": "SlotsController_2024_09_04_getAvailableSlots",
"summary": "Find out when is an event type ready to be booked.",
"summary": "Get available time slots for an event type",
"description": "\n There are 4 ways to get available slots for event type of an individual user:\n\n 1. By event type id. Event type id can be of user and team event types. Example '/v2/slots?eventTypeId=10&start=2050-09-05&end=2050-09-06&timeZone=Europe/Rome'\n\n 2. By event type slug + username. Example '/v2/slots?eventTypeSlug=intro&username=bob&start=2050-09-05&end=2050-09-06'\n\n 3. By event type slug + username + organization slug when searching within an organization. Example '/v2/slots?organizationSlug=org-slug&eventTypeSlug=intro&username=bob&start=2050-09-05&end=2050-09-06'\n\n 4. By usernames only (used for dynamic event type - there is no specific event but you want to know when 2 or more people are available). Example '/v2/slots?usernames=alice,bob&username=bob&organizationSlug=org-slug&start=2050-09-05&end=2050-09-06'. As you see you also need to provide the slug of the organization to which each user in the 'usernames' array belongs.\n\n And 3 ways to get available slots for team event type:\n\n 1. By team event type id. Example '/v2/slots?eventTypeId=10&start=2050-09-05&end=2050-09-06&timeZone=Europe/Rome'\n\n 2. By team event type slug + team slug. Example '/v2/slots?eventTypeSlug=intro&teamSlug=team-slug&start=2050-09-05&end=2050-09-06'\n\n 3. By team event type slug + team slug + organization slug when searching within an organization. Example '/v2/slots?organizationSlug=org-slug&eventTypeSlug=intro&teamSlug=team-slug&start=2050-09-05&end=2050-09-06'\n\n All of them require \"start\" and \"end\" query parameters which define the time range for which available slots should be checked.\n Optional parameters are:\n - timeZone: Time zone in which the available slots should be returned. Defaults to UTC.\n - duration: Only use for event types that allow multiple durations or for dynamic event types. If not passed for multiple duration event types defaults to default duration. For dynamic event types defaults to 30 aka each returned slot is 30 minutes long. So duration=60 means that returned slots will be each 60 minutes long.\n - format: Format of the slots. By default return is an object where each key is date and value is array of slots as string. If you want to get start and end of each slot use \"range\" as value.\n - bookingUidToReschedule: When rescheduling an existing booking, provide the booking's unique identifier to exclude its time slot from busy time calculations. This ensures the original booking time appears as available for rescheduling.\n ",
"parameters": [
{
@@ -11437,7 +11437,7 @@
},
"patch": {
"operationId": "SlotsController_2024_09_04_updateReservedSlot",
"summary": "Updated reserved a slot",
"summary": "Update a reserved slot",
"parameters": [
{
"name": "cal-api-version",
@@ -11530,7 +11530,7 @@
"/v2/stripe/connect": {
"get": {
"operationId": "StripeController_redirect",
"summary": "Get stripe connect URL",
"summary": "Get Stripe connect URL",
"parameters": [
{
"name": "Authorization",
@@ -11562,7 +11562,7 @@
"/v2/stripe/save": {
"get": {
"operationId": "StripeController_save",
"summary": "Save stripe credentials",
"summary": "Save Stripe credentials",
"parameters": [
{
"name": "state",
@@ -11601,7 +11601,7 @@
"/v2/stripe/check": {
"get": {
"operationId": "StripeController_check",
"summary": "Check stripe connection",
"summary": "Check Stripe connection",
"parameters": [
{
"name": "Authorization",
@@ -13219,7 +13219,7 @@
},
"get": {
"operationId": "WebhooksController_getWebhooks",
"summary": "Get all webooks",
"summary": "Get all webhooks",
"description": "Gets a paginated list of webhooks for the authenticated user.",
"parameters": [
{