Merge pull request #65 from NYCU-SDC/docs/badge

Add more examples

Author: elvisdragonmao

.github/workflows/deploy.yml

@@ -1,4 +1,4 @@
-name: Deploy API docs and mock server
+name: Deploy API Docs and Mock Server
 
 on:
   push:

README.md

@@ -1,6 +1,8 @@
 # Core System API
 
-Core System API defined using TypeSpec
+[![Test Build and Format](https://github.com/NYCU-SDC/core-system-api/actions/workflows/test.yml/badge.svg)](https://github.com/NYCU-SDC/core-system-api/actions/workflows/test.yml) [![Release SDK](https://github.com/NYCU-SDC/core-system-api/actions/workflows/sdk.yml/badge.svg)](https://github.com/NYCU-SDC/core-system-api/actions/workflows/sdk.yml) [![npm version](https://badge.fury.io/js/%40nycu-sdc%2Fcore-system-sdk.svg)](https://www.npmjs.com/package/@nycu-sdc/core-system-sdk)
+
+Core System API defined using TypeSpec.
 
 ```mermaid
 flowchart TD

src/auth/models.tsp

@@ -9,6 +9,7 @@ namespace CoreSystem.Auth {
 		nycu: "NYCU",
 	}
 
+	@example(#{ accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", expirationTime: 1735689600, refreshToken: "d290f1ee-6c54-4b01-90e6-d701748f0851" })
 	model RefreshToken {
 		@doc("The access token and formatted as JWT")
 		accessToken: string;
@@ -20,11 +21,13 @@ namespace CoreSystem.Auth {
 		refreshToken: string;
 	}
 
+	@example(#{ uid: "3c5fa073-7b97-43a3-bc44-ddc98f390a08" })
 	model InternalLoginRequest {
 		@doc("The user ID to login as.")
 		uid: string;
 	}
 
+	@example(#{ message: "Login successful" })
 	model InternalLoginResponse {
 		@doc("Login status message.")
 		message: string;

src/error/models.tsp

@@ -1,6 +1,7 @@
 namespace CoreSystem {
 	@error
 	@doc("Problem represents a problem detail as defined in RFC 7807")
+	@example(#{ title: "Bad Request", status: 400, type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", detail: "Invalid request parameters" })
 	model ProblemDetail {
 		@doc("The problem's title.")
 		title: string;
@@ -16,6 +17,7 @@ namespace CoreSystem {
 	}
 
 	@error
+	@example(#{ title: "Unauthorized", status: 401, type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401", detail: "Authentication credentials were missing or invalid" })
 	model Unauthorized {
 		title: "Unauthorized";
 		status: 401;
@@ -24,6 +26,7 @@ namespace CoreSystem {
 	}
 
 	@error
+	@example(#{ title: "Not Found", status: 404, type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404", detail: "The requested resource was not found" })
 	model NotFound {
 		title: "Not Found";
 		status: 404;
@@ -32,6 +35,7 @@ namespace CoreSystem {
 	}
 
 	@error
+	@example(#{ title: "Bad Request", status: 400, type: "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", detail: "The request body contains invalid data" })
 	model BadRequest {
 		title: "Bad Request";
 		status: 400;

src/form/answer/models.tsp

@@ -101,6 +101,16 @@ namespace CoreSystem.Responses {
 	}
 
 	@doc("Response model for the uploaded files and auto-created answer")
+	@example(#{
+		id: "a12b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
+		answer: #{
+			createdAt: utcDateTime.fromISO("2025-02-15T10:00:00Z"),
+			updatedAt: utcDateTime.fromISO("2025-02-17T16:45:00Z"),
+			responseId: "a12b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
+			answer: #{ questionId: "ee894524-4bd8-4a64-8fd2-a53b39ca94cd", questionType: CoreSystem.Forms.QuestionTypes.shortText, value: "John Doe" },
+			displayValue: "John Doe",
+		},
+	})
 	model QuestionFilesUploadResponse {
 		@doc("The response's unique identifier.")
 		id: uuid;
@@ -109,6 +119,16 @@ namespace CoreSystem.Responses {
 		answer: AnswerPayload;
 	}
 
+	@example(#{
+		id: "a12b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
+		answer: #{
+			createdAt: utcDateTime.fromISO("2025-02-15T10:00:00Z"),
+			updatedAt: utcDateTime.fromISO("2025-02-17T16:45:00Z"),
+			responseId: "a12b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
+			answer: #{ questionId: "ee894524-4bd8-4a64-8fd2-a53b39ca94cd", questionType: CoreSystem.Forms.QuestionTypes.shortText, value: "John Doe" },
+			displayValue: "John Doe",
+		},
+	})
 	model GetQuestionResponse {
 		@doc("Response ID that this question answer belongs to.")
 		id: uuid;
@@ -117,6 +137,25 @@ namespace CoreSystem.Responses {
 	}
 
 	@doc("Contains the question details and the corresponding answer for a specific question in a response")
+	@example(#{
+		question: #{
+			id: "ee894524-4bd8-4a64-8fd2-a53b39ca94cd",
+			sectionId: "b23f2668-c2dc-4213-88fe-eceedff46398",
+			required: true,
+			type: CoreSystem.Forms.QuestionTypes.shortText,
+			title: "What's your name?",
+			description: "Please enter your full name",
+			createdAt: utcDateTime.fromISO("2025-01-20T10:00:00Z"),
+			updatedAt: utcDateTime.fromISO("2025-02-01T15:30:00Z"),
+		},
+		payload: #{
+			createdAt: utcDateTime.fromISO("2025-02-15T10:00:00Z"),
+			updatedAt: utcDateTime.fromISO("2025-02-17T16:45:00Z"),
+			responseId: "a12b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
+			answer: #{ questionId: "ee894524-4bd8-4a64-8fd2-a53b39ca94cd", questionType: CoreSystem.Forms.QuestionTypes.shortText, value: "John Doe" },
+			displayValue: "John Doe",
+		},
+	})
 	model AnswersDetail {
 		@doc("The question details.")
 		question: CoreSystem.Forms.QuestionResponse;
@@ -126,6 +165,13 @@ namespace CoreSystem.Responses {
 	}
 
 	@doc("Contains the details of an answer for a specific question in a response")
+	@example(#{
+		createdAt: utcDateTime.fromISO("2025-02-15T10:00:00Z"),
+		updatedAt: utcDateTime.fromISO("2025-02-17T16:45:00Z"),
+		responseId: "a12b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
+		answer: #{ questionId: "ee894524-4bd8-4a64-8fd2-a53b39ca94cd", questionType: CoreSystem.Forms.QuestionTypes.shortText, value: "John Doe" },
+		displayValue: "John Doe",
+	})
 	model AnswerPayload {
 		@doc("The creation timestamp of the answer.")
 		createdAt: utcDateTime;

src/form/models.tsp

@@ -7,6 +7,7 @@ namespace CoreSystem.Forms {
 	}
 
 	@doc("Response after uploading a cover image.")
+	@example(#{ imageUrl: "https://example.com/images/form-cover-123.webp" })
 	model FormCoverUploadResponse {
 		@doc("The temporary full URL of the uploaded image.")
 		imageUrl: string;
@@ -47,6 +48,24 @@ namespace CoreSystem.Forms {
 	}
 
 	@doc("The structure of a form.")
+	@example(#{
+		id: "9a843aa0-8451-4e3b-b6a0-8c0e994e9040",
+		title: "SDC 2025 Recruitment Form",
+		description: "Join us for an exciting journey in software development!",
+		previewMessage: "Join us for an exciting journey",
+		status: FormStatus.published,
+		unitId: "d26e9c90-4747-496b-9953-7e7c4f97643f",
+		lastEditor: "3c5fa073-7b97-43a3-bc44-ddc98f390a08",
+		deadline: utcDateTime.fromISO("2025-03-31T23:59:59Z"),
+		publishTime: utcDateTime.fromISO("2025-02-01T00:00:00Z"),
+		messageAfterSubmission: "Thank you for your application! We'll get back to you soon.",
+		dressing: #{ color: "#0066cc", headerFont: "LINESeedTW", questionFont: "LINESeedTW", textFont: "LINESeedTW" },
+		coverImage: "https://example.com/images/form-cover.webp",
+		googleSheetUrl: "https://docs.google.com/spreadsheets/d/1ABC123/edit",
+		visibility: FormVisibility.public,
+		createdAt: utcDateTime.fromISO("2025-01-15T10:00:00Z"),
+		updatedAt: utcDateTime.fromISO("2025-02-10T14:30:00Z"),
+	})
 	model Form {
 		@doc("The form's unique identifier.")
 		id: uuid;
@@ -114,6 +133,13 @@ namespace CoreSystem.Forms {
 	}
 
 	@doc("A section within a form, grouping questions together.")
+	@example(#{
+		id: "b23f2668-c2dc-4213-88fe-eceedff46398",
+		formId: "9a843aa0-8451-4e3b-b6a0-8c0e994e9040",
+		title: "Personal Information",
+		description: "Please provide your basic information",
+		questions: #[],
+	})
 	model Section {
 		@doc("Unique identifier.")
 		id: uuid;
@@ -159,12 +185,14 @@ namespace CoreSystem.Forms {
 	}
 
 	@doc("Response model for listing all sections and questions in a form.")
+	@example(#{ sections: #[] })
 	model ListSectionsResponse {
 		sections: Section[];
 	}
 
 	// form recipientUser
 	@doc("The basic info of a user that can receive the form.")
+	@example(#{ id: "3c5fa073-7b97-43a3-bc44-ddc98f390a08", name: "John Doe" })
 	model RecipientUser {
 		id: uuid;
 		name: string;
@@ -181,35 +209,41 @@ namespace CoreSystem.Forms {
 	}
 
 	@doc("The result of recipients selection (no duplicated).")
+	@example(#{ recipients: #[#{ id: "3c5fa073-7b97-43a3-bc44-ddc98f390a08", name: "John Doe" }] })
 	model RecipientSelectionResponse {
 		recipients: RecipientUser[];
 	}
 
 	@doc("Response after publishing a form.")
+	@example(#{ visibility: FormVisibility.public })
 	model FormPublishResponse {
 		@doc("The visibility setting of the form. Public forms are visible to all logged-in users. Private forms require a direct link to access.")
 		visibility: FormVisibility;
 	}
 
 	@doc("Response containing the Gmail address for Google Sheet permissions.")
+	@example(#{ email: "core-system-bot@example.com" })
 	model GoogleSheetEmailResponse {
 		@doc("The Gmail address that should be added to Google Sheet permissions so the system can modify the form.")
 		email: string;
 	}
 
 	@doc("Request body for verifying a Google Sheet URL.")
+	@example(#{ googleSheetUrl: "https://docs.google.com/spreadsheets/d/1ABC123XYZ/edit" })
 	model GoogleSheetVerifyRequest {
 		@doc("The Google Sheet URL provided by user.")
 		googleSheetUrl: string;
 	}
 
 	@doc("Verification result for the given Google Sheet URL.")
+	@example(#{ isValid: true })
 	model GoogleSheetVerifyResponse {
 		@doc("Indicates whether the Google Sheet URL is valid and accessible.")
 		isValid: boolean;
 	}
 
 	@doc("A font definition used in form dressing.")
+	@example(#{ id: "LINESeedTW", name: "LINE Seed TW" })
 	model Font {
 		@doc("The unique identifier of the font.")
 		id: string;

src/form/question/models.tsp

@@ -108,6 +108,7 @@ namespace CoreSystem.Forms {
 	}
 
 	@doc("Options for file upload questions.")
+	@example(#{ allowedFileTypes: #[allowedFileTypes.pdf, allowedFileTypes.doc, allowedFileTypes.docx], maxFileAmount: 3, maxFileSizeLimit: 5242880 })
 	model UploadFileOption {
 		@doc("Allowed file types/extensions.")
 		allowedFileTypes: allowedFileTypes[];
@@ -124,6 +125,7 @@ namespace CoreSystem.Forms {
 	}
 
 	@doc("Options for linear scale and rating questions.")
+	@example(#{ icon: "star", minVal: 1, maxVal: 5, minValueLabel: "Poor", maxValueLabel: "Excellent" })
 	model ScaleOption {
 		@doc("Background icon for the linear scale option.")
 		icon?: string;
@@ -142,6 +144,7 @@ namespace CoreSystem.Forms {
 	}
 
 	@doc("A choice option for creating/updating choice-based questions.")
+	@example(#{ name: "Option A", description: "This is option A" })
 	model ChoiceOption {
 		@doc("The name/text of the choice option.")
 		name: string;
@@ -151,6 +154,7 @@ namespace CoreSystem.Forms {
 	}
 
 	@doc("A choice with ID and name for choice-based questions.")
+	@example(#{ id: "f421cfc2-2b84-4da9-9629-011af609935a", name: "Backend", description: "Backend development team" })
 	model Choice {
 		@doc("The unique identifier of the choice.")
 		id: uuid;
@@ -163,6 +167,7 @@ namespace CoreSystem.Forms {
 	}
 
 	@doc("Options for date questions.")
+	@example(#{ hasYear: true, hasMonth: true, hasDay: true, minDate: utcDateTime.fromISO("2025-01-01T00:00:00Z"), maxDate: utcDateTime.fromISO("2025-12-31T23:59:59Z") })
 	model DateOption {
 		@doc("Whether the year component is required for the date.")
 		hasYear: boolean;
@@ -181,6 +186,16 @@ namespace CoreSystem.Forms {
 	}
 
 	@doc("Response model for the detailed structure of a question.")
+	@example(#{
+		id: "ee894524-4bd8-4a64-8fd2-a53b39ca94cd",
+		sectionId: "b23f2668-c2dc-4213-88fe-eceedff46398",
+		required: true,
+		type: QuestionTypes.shortText,
+		title: "What's your name?",
+		description: "Please enter your full name",
+		createdAt: utcDateTime.fromISO("2025-01-20T10:00:00Z"),
+		updatedAt: utcDateTime.fromISO("2025-02-01T15:30:00Z"),
+	})
 	model QuestionResponse {
 		@doc("The question's unique identifier.")
 		id: uuid;

src/form/response/models.tsp

@@ -2,12 +2,18 @@ using Http;
 
 namespace CoreSystem.Responses {
 	@doc("Response model for creating a form response")
+	@example(#{ id: "a12b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6" })
 	model CreateResponse {
 		@doc("The response's unique identifier.")
 		id: uuid;
 	}
 
 	@doc("Response model for updating a form response")
+	@example(#{
+		id: "a12b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
+		updatedAt: utcDateTime.fromISO("2025-02-17T16:45:00Z"),
+		answers: #[],
+	})
 	model UpdateResponse {
 		@doc("The response's unique identifier.")
 		id: uuid;
@@ -20,6 +26,12 @@ namespace CoreSystem.Responses {
 	}
 
 	@doc("Response model for a single response in list view")
+	@example(#{
+		id: "a12b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
+		submittedBy: "3c5fa073-7b97-43a3-bc44-ddc98f390a08",
+		createdAt: utcDateTime.fromISO("2025-02-15T10:00:00Z"),
+		updatedAt: utcDateTime.fromISO("2025-02-17T16:45:00Z"),
+	})
 	model Response {
 		@doc("The response's unique identifier.")
 		id: uuid;
@@ -35,6 +47,7 @@ namespace CoreSystem.Responses {
 	}
 
 	@doc("Response model for listing all responses of a form")
+	@example(#{ formId: "9a843aa0-8451-4e3b-b6a0-8c0e994e9040", responses: #[] })
 	model ListResponse {
 		@doc("The form ID.")
 		formId: uuid;
@@ -44,6 +57,12 @@ namespace CoreSystem.Responses {
 	}
 
 	@doc("Response model for getting a specific form response")
+	@example(#{
+		id: "a12b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
+		formId: "9a843aa0-8451-4e3b-b6a0-8c0e994e9040",
+		progress: ResponseProgress.draft,
+		sections: #[],
+	})
 	model GetFormResponse {
 		@doc("The response's unique identifier.")
 		id: uuid;
@@ -68,6 +87,12 @@ namespace CoreSystem.Responses {
 	}
 
 	@doc("Response model for a single section in response sections view")
+	@example(#{
+		id: "b23f2668-c2dc-4213-88fe-eceedff46398",
+		title: "Personal Information",
+		progress: SectionProgress.draft,
+		answerDetails: #[],
+	})
 	model ResponseSections {
 		@doc("Unique identifier.")
 		id: uuid;