commonscomputer/cal.diy
4
0
Fork 0
Code Issues Pull Requests Actions 2.0k Packages Projects Releases Wiki Activity

chore: Automated API v2 OpenAPI spec generation (#17046)

Browse Source 
* chore: Automated API v2 OpenAPI spec generation

* chore: update docs

---------

Co-authored-by: Morgan <33722304+ThyMinimalDev@users.noreply.github.com>
Co-authored-by: Morgan Vernay <morgan@cal.com>
This commit is contained in:
Keith Williams
2024-11-13 15:28:25 +00:00
committed by GitHub
co-authored by Morgan Morgan Vernay
parent 5c6e60b726
commit 74b4d7a94a
5 changed files with 1201 additions and 465 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/api/v2/src/main.ts
+12 -4
View File
@@ -1,4 +1,5 @@
import type { AppConfig } from "@/config/type";
import { getEnv } from "@/env";
import { Logger } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import { NestFactory } from "@nestjs/core";
@@ -107,13 +108,20 @@ async function generateSwagger(app: NestExpressApplication<Server>) {
const document = SwaggerModule.createDocument(app, config);
document.paths = groupAndSortPathsByFirstTag(document.paths);
const outputFile = "./swagger/documentation.json";
const swaggerOutputFile = "./swagger/documentation.json";
const docsOutputFile = "../../../docs/api-reference/v2/openapi.json";
const stringifiedContents = JSON.stringify(document, null, 2);
if (fs.existsSync(outputFile)) {
fs.unlinkSync(outputFile);
if (fs.existsSync(swaggerOutputFile)) {
fs.unlinkSync(swaggerOutputFile);
}
fs.writeFileSync(outputFile, JSON.stringify(document, null, 2), { encoding: "utf8" });
fs.writeFileSync(swaggerOutputFile, stringifiedContents, { encoding: "utf8" });
if (fs.existsSync(docsOutputFile) && getEnv("NODE_ENV") === "development") {
fs.unlinkSync(docsOutputFile);
fs.writeFileSync(docsOutputFile, stringifiedContents, { encoding: "utf8" });
}
if (!process.env.DOCS_URL) {
SwaggerModule.setup("docs", app, document, {
apps/api/v2/src/modules/oauth-clients/controllers/oauth-flow/oauth-flow.controller.ts
+3 -29
View File
@@ -25,9 +25,9 @@ import {
import {
ApiTags as DocsTags,
ApiExcludeController as DocsExcludeController,
ApiExcludeEndpoint as DocsExcludeEndpoint,
ApiOperation as DocsOperation,
ApiOkResponse as DocsOkResponse,
ApiExcludeEndpoint as DocsExcludeEndpoint,
ApiBadRequestResponse as DocsBadRequestResponse,
ApiHeader as DocsHeader,
} from "@nestjs/swagger";
@@ -50,20 +50,7 @@ export class OAuthFlowController {
@Post("/authorize")
@HttpCode(HttpStatus.OK)
@UseGuards(NextAuthGuard)
@DocsOperation({
summary: "Authorize an OAuth client",
description:
"Redirects the user to the specified 'redirect_uri' with an authorization code in query parameter if the client is authorized successfully. The code is then exchanged for access and refresh tokens via the `/exchange` endpoint.",
})
@DocsOkResponse({
description:
"The user is redirected to the 'redirect_uri' with an authorization code in query parameter e.g. `redirectUri?code=secretcode.`",
})
@DocsBadRequestResponse({
description:
"Bad request if the OAuth client is not found, if the redirect URI is invalid, or if the user has already authorized the client.",
})
@DocsExcludeEndpoint(getEnv("NODE_ENV") === "production")
@DocsExcludeEndpoint()
async authorize(
@Param("clientId") clientId: string,
@Body() body: OAuthAuthorizeInput,
@@ -97,20 +84,7 @@ export class OAuthFlowController {
@Post("/exchange")
@HttpCode(HttpStatus.OK)
@DocsOperation({
summary: "Exchange authorization code for access tokens",
description:
"Exchanges the authorization code received from the `/authorize` endpoint for access and refresh tokens. The authorization code should be provided in the 'Authorization' header prefixed with 'Bearer '.",
})
@DocsOkResponse({
type: KeysResponseDto,
description: "Successfully exchanged authorization code for access and refresh tokens.",
})
@DocsBadRequestResponse({
description:
"Bad request if the authorization code is missing, invalid, or if the client ID and secret do not match.",
})
@DocsExcludeEndpoint(getEnv("NODE_ENV") === "production")
@DocsExcludeEndpoint()
async exchange(
@Headers("Authorization") authorization: string,
@Param("clientId") clientId: string,
apps/api/v2/src/modules/webhooks/controllers/webhooks.controller.ts
+4 -1
View File
@@ -82,7 +82,10 @@ export class WebhooksController {
}
@Get("/")
@ApiOperation({ summary: "Get all webooks (paginated)" })
@ApiOperation({
summary: "Get all webooks",
description: "Gets a paginated list of webhooks for the authenticated user.",
})
async getWebhooks(
@GetUser() user: UserWithProfile,
@Query() query: SkipTakePagination
apps/api/v2/swagger/documentation.json
+104 -116
View File
@@ -4438,97 +4438,6 @@
]
}
},
"/v2/oauth/{clientId}/authorize": {
"post": {
"operationId": "OAuthFlowController_authorize",
"summary": "Authorize an OAuth client",
"description": "Redirects the user to the specified 'redirect_uri' with an authorization code in query parameter if the client is authorized successfully. The code is then exchanged for access and refresh tokens via the `/exchange` endpoint.",
"parameters": [
{
"name": "clientId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OAuthAuthorizeInput"
}
}
}
},
"responses": {
"200": {
"description": "The user is redirected to the 'redirect_uri' with an authorization code in query parameter e.g. `redirectUri?code=secretcode.`"
},
"400": {
"description": "Bad request if the OAuth client is not found, if the redirect URI is invalid, or if the user has already authorized the client."
}
},
"tags": [
"OAuth"
]
}
},
"/v2/oauth/{clientId}/exchange": {
"post": {
"operationId": "OAuthFlowController_exchange",
"summary": "Exchange authorization code for access tokens",
"description": "Exchanges the authorization code received from the `/authorize` endpoint for access and refresh tokens. The authorization code should be provided in the 'Authorization' header prefixed with 'Bearer '.",
"parameters": [
{
"name": "Authorization",
"required": true,
"in": "header",
"schema": {
"type": "string"
}
},
{
"name": "clientId",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExchangeAuthorizationCodeInput"
}
}
}
},
"responses": {
"200": {
"description": "Successfully exchanged authorization code for access and refresh tokens.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KeysResponseDto"
}
}
}
},
"400": {
"description": "Bad request if the authorization code is missing, invalid, or if the client ID and secret do not match."
}
},
"tags": [
"OAuth"
]
}
},
"/v2/oauth/{clientId}/refresh": {
"post": {
"operationId": "OAuthFlowController_refreshAccessToken",
@@ -5343,7 +5252,8 @@
},
"get": {
"operationId": "WebhooksController_getWebhooks",
"summary": "Get all webooks (paginated)",
"summary": "Get all webooks",
"description": "Gets a paginated list of webhooks for the authenticated user.",
"parameters": [
{
"name": "take",
@@ -6073,28 +5983,6 @@
}
}
},
"OAuthAuthorizeInput": {
"type": "object",
"properties": {
"redirectUri": {
"type": "string"
}
},
"required": [
"redirectUri"
]
},
"ExchangeAuthorizationCodeInput": {
"type": "object",
"properties": {
"clientSecret": {
"type": "string"
}
},
"required": [
"clientSecret"
]
},
"RefreshTokenInput": {
"type": "object",
"properties": {
@@ -6975,6 +6863,18 @@
"type": "number",
"example": 60
},
"lengthInMinutesOptions": {
"example": [
15,
30,
60
],
"description": "If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.",
"type": "array",
"items": {
"type": "string"
}
},
"title": {
"type": "string",
"example": "Learn the secrets of masterchief!"
@@ -7198,6 +7098,7 @@
},
"required": [
"lengthInMinutes",
"lengthInMinutesOptions",
"title",
"slug"
]
@@ -8340,6 +8241,18 @@
"type": "number",
"example": 60
},
"lengthInMinutesOptions": {
"example": [
15,
30,
60
],
"description": "If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.",
"type": "array",
"items": {
"type": "string"
}
},
"title": {
"type": "string",
"example": "Learn the secrets of masterchief!"
@@ -8563,6 +8476,7 @@
"required": [
"id",
"lengthInMinutes",
"lengthInMinutesOptions",
"title",
"slug",
"description",
@@ -8678,6 +8592,18 @@
"type": "number",
"example": 60
},
"lengthInMinutesOptions": {
"example": [
15,
30,
60
],
"description": "If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.",
"type": "array",
"items": {
"type": "string"
}
},
"title": {
"type": "string",
"example": "Learn the secrets of masterchief!"
@@ -8898,7 +8824,10 @@
"hideCalendarEventDetails": {
"type": "boolean"
}
}
},
"required": [
"lengthInMinutesOptions"
]
},
"UpdateEventTypeOutput_2024_06_14": {
"type": "object",
@@ -10157,6 +10086,18 @@
"type": "number",
"example": 60
},
"lengthInMinutesOptions": {
"example": [
15,
30,
60
],
"description": "If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.",
"type": "array",
"items": {
"type": "string"
}
},
"title": {
"type": "string",
"example": "Learn the secrets of masterchief!"
@@ -10393,6 +10334,7 @@
},
"required": [
"lengthInMinutes",
"lengthInMinutesOptions",
"title",
"slug",
"schedulingType",
@@ -10474,6 +10416,19 @@
"minimum": 1,
"example": 60
},
"lengthInMinutesOptions": {
"example": [
15,
30,
60
],
"description": "If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.",
"type": "array",
"items": {
"type": "number",
"minimum": 1
}
},
"title": {
"type": "string",
"example": "Learn the secrets of masterchief!"
@@ -10899,6 +10854,18 @@
"type": "number",
"example": 60
},
"lengthInMinutesOptions": {
"example": [
15,
30,
60
],
"description": "If you want that user can choose between different lengths of the event you can specify them here. Must include the provided `lengthInMinutes`.",
"type": "array",
"items": {
"type": "string"
}
},
"title": {
"type": "string",
"example": "Learn the secrets of masterchief!"
@@ -11129,7 +11096,10 @@
"type": "boolean",
"description": "If true, all current and future team members will be assigned to this event type"
}
}
},
"required": [
"lengthInMinutesOptions"
]
},
"UpdateTeamEventTypeOutput": {
"type": "object",
@@ -12839,6 +12809,11 @@
"description": "The start time of the booking in ISO 8601 format in UTC timezone.",
"example": "2024-08-13T09:00:00Z"
},
"lengthInMinutes": {
"type": "number",
"example": 30,
"description": "If it is an event type that has multiple possible lengths that attendee can pick from, you can pass the desired booking length here.\n If not provided then event type default length will be used for the booking."
},
"eventTypeId": {
"type": "number",
"description": "The ID of the event type that is booked.",
@@ -12884,6 +12859,7 @@
},
"required": [
"start",
"lengthInMinutes",
"eventTypeId",
"attendee"
]
@@ -12896,6 +12872,11 @@
"description": "The start time of the booking in ISO 8601 format in UTC timezone.",
"example": "2024-08-13T09:00:00Z"
},
"lengthInMinutes": {
"type": "number",
"example": 30,
"description": "If it is an event type that has multiple possible lengths that attendee can pick from, you can pass the desired booking length here.\n If not provided then event type default length will be used for the booking."
},
"eventTypeId": {
"type": "number",
"description": "The ID of the event type that is booked.",
@@ -12946,6 +12927,7 @@
},
"required": [
"start",
"lengthInMinutes",
"eventTypeId",
"attendee",
"instant"
@@ -12959,6 +12941,11 @@
"description": "The start time of the booking in ISO 8601 format in UTC timezone.",
"example": "2024-08-13T09:00:00Z"
},
"lengthInMinutes": {
"type": "number",
"example": 30,
"description": "If it is an event type that has multiple possible lengths that attendee can pick from, you can pass the desired booking length here.\n If not provided then event type default length will be used for the booking."
},
"eventTypeId": {
"type": "number",
"description": "The ID of the event type that is booked.",
@@ -13009,6 +12996,7 @@
},
"required": [
"start",
"lengthInMinutes",
"eventTypeId",
"attendee"
]
docs/api-reference/v2/openapi.json
+1078 -315
View File
File diff suppressed because it is too large Load Diff