docs(websoc): add openapi specifications to schema #87

vinnyho · 2025-01-16T18:55:24Z

Description

Added openapi query & response specifications in websoc.ts based off of larc.ts

Related Issue

Closes #79

Motivation and Context

Improve API documentation by adding openapi specifications for WebSoc endpoints
Makes it easier for API consumers and developers

How Has This Been Tested?

Ran locally with changes

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

My code involves a change to the database schema.
My code requires a change to the documentation.

laggycomputer

Great progress! There are some inaccuracies that need addressing, but clean those up and these are great additions.

apps/api/src/schema/websoc.ts

vinnyho · 2025-01-18T01:23:13Z

Thanks for the suggestions, I apologize you had to leave a lot of suggestions on the PR that was bad of me

I added your suggested fixes, and added more clarification by including 'WebSoc' in the descriptions as larc.ts did. Please let me know if there are any other fixes necessary. Thanks!

apps/api/src/schema/websoc.ts

laggycomputer · 2025-01-18T06:46:39Z

Please also ensure you resolve the merge conflict, mark previous comments you've fixed as resolved, and modify the PR title pursuant to the conventional commits standard. Your PR will be squashed and rebased onto main using the PR title as the commit title and we require such commit titles follow conventional commits. This is also probably not a "feature update" since your changes are solely to documentation.

andrew-wang0 · 2025-01-20T23:07:38Z

@vinnyho looks like a lot of good progress so far! One small nitpick, could you rename the PR title to follow conventional commits

Something like docs(websoc): add openapi specifications to schema

vinnyho · 2025-01-21T03:50:56Z

The merge conflict conflict seems to be happening as I add the description and example for quarter and year, I don't think I can resolve it without just removing what I added.

laggycomputer · 2025-01-21T04:00:35Z

The merge conflict conflict seems to be happening as I add the description and example for quarter and year, I don't think I can resolve it without just removing what I added.

A correct merge conflict resolution is an actual merge commit with the tip of your PR branch as first parent and origin/main as the second parent, or a cherrypick of such a merge commit. You need to make this merge commit yourself.

vinnyho · 2025-01-21T04:27:56Z

I believe I fixed the issue, but I don't know for sure. This is my first time dealing with merging conflicts as I didn't come across it with other PRs. Please let me know if I did anything wrong thank you

apps/api/src/schema/lib/day.ts

apps/api/src/schema/websoc.ts

laggycomputer · 2025-01-21T04:35:16Z

apps/api/src/schema/websoc.ts

  ge: z
    .enum(geCategories)
    .optional()
+    .openapi({ description: "The general education category of the course", example: "GE-1A" })


Comment about singular course and notion of query search parameter vis-a-vis response subfield stands throughout this review.

apps/api/src/schema/websoc.ts

laggycomputer · 2025-01-21T04:41:24Z

apps/api/src/schema/websoc.ts

  sectionCodes: z
    .string()
    .optional()
+    .openapi({
+      description: "The section code of the course",
+      example: "35530",


The example should be expanded accordingly.

laggycomputer · 2025-01-21T04:43:21Z

apps/api/src/schema/websoc.ts

    .transform((x) => (x === "ANY" ? undefined : x)),
  sectionType: z
    .union([z.enum(anyArray), z.enum(websocSectionTypes)])
    .optional()
+    .openapi({
+      description: "Filter courses by section type",


Expanding on the comment extending throughout this review: A section type describes a section; a course as a whole is not a lecture or recitation. In fact, a course can have sections of only one type or of multiple. Then it doesn't make sense to claim you can "filter courses by section type". Reword accordingly.

laggycomputer · 2025-01-21T04:43:48Z

apps/api/src/schema/websoc.ts

+  }),
+  units: z.optional(z.literal("VAR").or(z.string())).openapi({
+    description:
+      "Filter courses by unit count. 'VAR' filters for courses with variable unit ranges (e.g., '1-4')",


That is not all of the functionality of this parameter.

laggycomputer · 2025-01-21T04:45:23Z

apps/api/src/schema/websoc.ts

  excludeRestrictionCodes: z
    .string()
    .optional()
+    .openapi({
+      description:
+        "Exclude courses by comma-separated restriction codes, see [Registrar's list](https://www.reg.uci.edu/enrollment/restrict_codes.html)",


Earlier comment about a different display name for this link stands. You also need to clearly indicate in text that this is a link; look at your local copy of the REST reference to see why the current description is problematic.

openapi

apps/api/src/schema/websoc.ts

Vincent Ho added 3 commits January 16, 2025 10:29

Added openapi specifications

e0dfa87

Fixed formatting

fa1f936

Consistent formatting

2250280

laggycomputer self-requested a review January 16, 2025 19:01

laggycomputer requested changes Jan 16, 2025

View reviewed changes

vinnyho requested a review from laggycomputer January 18, 2025 01:23

laggycomputer requested changes Jan 18, 2025

View reviewed changes

vinnyho force-pushed the openapi branch from 2e6e60e to 2250280 Compare January 21, 2025 02:50

vinnyho changed the title ~~Add openapi query & response specifications to WebSoc schemas~~ docs(websoc): add openapi specifications to schema Jan 21, 2025

Vincent Ho added 2 commits January 20, 2025 19:42

fix: changed improper usage of course/section

ff6e66a

fix merge conflict

130fc9b

Merge remote-tracking branch 'upstream/main' into openapi

eb7773f

laggycomputer requested changes Jan 21, 2025

View reviewed changes

apps/api/src/schema/websoc.ts Show resolved Hide resolved

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(websoc): add openapi specifications to schema #87

docs(websoc): add openapi specifications to schema #87

vinnyho commented Jan 16, 2025 •

edited

Loading

laggycomputer left a comment

vinnyho commented Jan 18, 2025

laggycomputer commented Jan 18, 2025 •

edited

Loading

andrew-wang0 commented Jan 20, 2025 •

edited

Loading

vinnyho commented Jan 21, 2025

laggycomputer commented Jan 21, 2025 •

edited

Loading

vinnyho commented Jan 21, 2025

laggycomputer Jan 21, 2025

laggycomputer Jan 21, 2025

laggycomputer Jan 21, 2025

laggycomputer Jan 21, 2025

laggycomputer Jan 21, 2025

docs(websoc): add openapi specifications to schema #87

Are you sure you want to change the base?

docs(websoc): add openapi specifications to schema #87

Conversation

vinnyho commented Jan 16, 2025 • edited Loading

Description

Related Issue

Motivation and Context

How Has This Been Tested?

Types of changes

Checklist:

laggycomputer left a comment

Choose a reason for hiding this comment

vinnyho commented Jan 18, 2025

laggycomputer commented Jan 18, 2025 • edited Loading

andrew-wang0 commented Jan 20, 2025 • edited Loading

vinnyho commented Jan 21, 2025

laggycomputer commented Jan 21, 2025 • edited Loading

vinnyho commented Jan 21, 2025

laggycomputer Jan 21, 2025

Choose a reason for hiding this comment

laggycomputer Jan 21, 2025

Choose a reason for hiding this comment

laggycomputer Jan 21, 2025

Choose a reason for hiding this comment

laggycomputer Jan 21, 2025

Choose a reason for hiding this comment

laggycomputer Jan 21, 2025

Choose a reason for hiding this comment

vinnyho commented Jan 16, 2025 •

edited

Loading

laggycomputer commented Jan 18, 2025 •

edited

Loading

andrew-wang0 commented Jan 20, 2025 •

edited

Loading

laggycomputer commented Jan 21, 2025 •

edited

Loading