Skip to content

Commit 5610a75

Browse files
dacharycdacharyc
committed
Add Swagger annotations for new routes
1 parent de6d889 commit 5610a75

1 file changed

Lines changed: 279 additions & 20 deletions

File tree

‎server/express/src/routes/movies.ts‎

Lines changed: 279 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -119,42 +119,301 @@ const router = express.Router();
119119
router.get("/", asyncHandler(movieController.getAllMovies));
120120

121121
/**
122-
* GET /api/movies/search
123-
*
124-
* Search movies using MongoDB Search across multiple fields.
125-
* Demonstrates MongoDB Atlas Search with compound queries and fuzzy matching.
122+
* @swagger
123+
* /api/movies/search:
124+
* get:
125+
* summary: Search movies using MongoDB Atlas Search
126+
* description: Search movies using MongoDB Atlas Search across multiple fields with compound queries and fuzzy matching. Demonstrates MongoDB Atlas Search capabilities.
127+
* tags: [Movies]
128+
* parameters:
129+
* - in: query
130+
* name: plot
131+
* schema:
132+
* type: string
133+
* description: Search in plot field using phrase matching
134+
* example: detective solving mystery
135+
* - in: query
136+
* name: fullplot
137+
* schema:
138+
* type: string
139+
* description: Search in fullplot field using phrase matching
140+
* example: crime investigation
141+
* - in: query
142+
* name: directors
143+
* schema:
144+
* type: string
145+
* description: Search for directors with fuzzy matching
146+
* example: Christopher Nolan
147+
* - in: query
148+
* name: writers
149+
* schema:
150+
* type: string
151+
* description: Search for writers with fuzzy matching
152+
* example: Quentin Tarantino
153+
* - in: query
154+
* name: cast
155+
* schema:
156+
* type: string
157+
* description: Search for cast members with fuzzy matching
158+
* example: Tom Hanks
159+
* - in: query
160+
* name: searchOperator
161+
* schema:
162+
* type: string
163+
* enum: [must, should, mustNot, filter]
164+
* default: must
165+
* description: Search operator for compound queries
166+
* - in: query
167+
* name: limit
168+
* schema:
169+
* type: integer
170+
* default: 20
171+
* maximum: 100
172+
* description: Number of results to return
173+
* - in: query
174+
* name: skip
175+
* schema:
176+
* type: integer
177+
* default: 0
178+
* description: Number of documents to skip for pagination
179+
* responses:
180+
* 200:
181+
* description: Search results
182+
* content:
183+
* application/json:
184+
* schema:
185+
* allOf:
186+
* - $ref: '#/components/schemas/SuccessResponse'
187+
* - type: object
188+
* properties:
189+
* data:
190+
* type: object
191+
* properties:
192+
* movies:
193+
* type: array
194+
* items:
195+
* $ref: '#/components/schemas/Movie'
196+
* count:
197+
* type: integer
198+
* limit:
199+
* type: integer
200+
* skip:
201+
* type: integer
202+
* 400:
203+
* description: Bad request - invalid search operator or no search parameters provided
204+
* content:
205+
* application/json:
206+
* schema:
207+
* $ref: '#/components/schemas/ErrorResponse'
126208
*/
127209
router.get("/search", asyncHandler(movieController.searchMovies));
128210

129211
/**
130-
* GET /api/movies/vector-search
131-
*
132-
* Search movies using MongoDB Vector Search for semantic similarity.
133-
* Demonstrates vector search using embeddings to find similar plots.
212+
* @swagger
213+
* /api/movies/vector-search:
214+
* get:
215+
* summary: Search movies using MongoDB Vector Search
216+
* description: Search movies using MongoDB Vector Search for semantic similarity. Demonstrates vector search using embeddings to find movies with similar plots. Requires VOYAGE_API_KEY to be configured.
217+
* tags: [Movies]
218+
* parameters:
219+
* - in: query
220+
* name: q
221+
* required: true
222+
* schema:
223+
* type: string
224+
* description: Search query for semantic similarity
225+
* example: space exploration and alien encounters
226+
* - in: query
227+
* name: limit
228+
* schema:
229+
* type: integer
230+
* default: 10
231+
* maximum: 50
232+
* description: Number of results to return
233+
* responses:
234+
* 200:
235+
* description: Vector search results with similarity scores
236+
* content:
237+
* application/json:
238+
* schema:
239+
* allOf:
240+
* - $ref: '#/components/schemas/SuccessResponse'
241+
* - type: object
242+
* properties:
243+
* data:
244+
* type: array
245+
* items:
246+
* allOf:
247+
* - $ref: '#/components/schemas/Movie'
248+
* - type: object
249+
* properties:
250+
* score:
251+
* type: number
252+
* description: Vector similarity score
253+
* 400:
254+
* description: Bad request - missing query parameter or VOYAGE_API_KEY not configured
255+
* content:
256+
* application/json:
257+
* schema:
258+
* $ref: '#/components/schemas/ErrorResponse'
134259
*/
135260
router.get("/vector-search", asyncHandler(movieController.vectorSearchMovies));
136261

137262
/**
138-
* GET /api/movies/aggregations/reportingByComments
139-
*
140-
* Aggregate movies with their most recent comments.
141-
* Demonstrates MongoDB $lookup aggregation to join collections.
263+
* @swagger
264+
* /api/movies/aggregations/reportingByComments:
265+
* get:
266+
* summary: Get movies with their most recent comments
267+
* description: Aggregate movies with their most recent comments using MongoDB $lookup aggregation. Demonstrates joining collections and sorting by nested fields.
268+
* tags: [Movies]
269+
* parameters:
270+
* - in: query
271+
* name: limit
272+
* schema:
273+
* type: integer
274+
* default: 10
275+
* maximum: 50
276+
* description: Number of recent comments to include per movie
277+
* - in: query
278+
* name: movieId
279+
* schema:
280+
* type: string
281+
* description: Optional MongoDB ObjectId to filter for a specific movie
282+
* example: 573a1390f29313caabcd4135
283+
* responses:
284+
* 200:
285+
* description: Movies with their most recent comments
286+
* content:
287+
* application/json:
288+
* schema:
289+
* allOf:
290+
* - $ref: '#/components/schemas/SuccessResponse'
291+
* - type: object
292+
* properties:
293+
* data:
294+
* type: array
295+
* items:
296+
* type: object
297+
* properties:
298+
* _id:
299+
* type: string
300+
* title:
301+
* type: string
302+
* year:
303+
* type: integer
304+
* genres:
305+
* type: array
306+
* items:
307+
* type: string
308+
* imdbRating:
309+
* type: number
310+
* recentComments:
311+
* type: array
312+
* items:
313+
* type: object
314+
* properties:
315+
* _id:
316+
* type: string
317+
* userName:
318+
* type: string
319+
* userEmail:
320+
* type: string
321+
* text:
322+
* type: string
323+
* date:
324+
* type: string
325+
* format: date-time
326+
* 400:
327+
* description: Invalid movie ID format
328+
* content:
329+
* application/json:
330+
* schema:
331+
* $ref: '#/components/schemas/ErrorResponse'
142332
*/
143333
router.get("/aggregations/reportingByComments", asyncHandler(movieController.getMoviesWithMostRecentComments));
144334

145335
/**
146-
* GET /api/movies/aggregations/reportingByYear
147-
*
148-
* Aggregate movies by year with statistics.
149-
* Demonstrates MongoDB $group aggregation for statistical calculations.
336+
* @swagger
337+
* /api/movies/aggregations/reportingByYear:
338+
* get:
339+
* summary: Get movie statistics by year
340+
* description: Aggregate movies by year with statistics including count, average rating, highest/lowest ratings, and total votes. Demonstrates MongoDB $group aggregation for statistical calculations.
341+
* tags: [Movies]
342+
* responses:
343+
* 200:
344+
* description: Movie statistics grouped by year
345+
* content:
346+
* application/json:
347+
* schema:
348+
* allOf:
349+
* - $ref: '#/components/schemas/SuccessResponse'
350+
* - type: object
351+
* properties:
352+
* data:
353+
* type: array
354+
* items:
355+
* type: object
356+
* properties:
357+
* year:
358+
* type: integer
359+
* example: 1994
360+
* movieCount:
361+
* type: integer
362+
* example: 150
363+
* averageRating:
364+
* type: number
365+
* example: 7.25
366+
* highestRating:
367+
* type: number
368+
* example: 9.3
369+
* lowestRating:
370+
* type: number
371+
* example: 4.5
372+
* totalVotes:
373+
* type: integer
374+
* example: 1500000
150375
*/
151376
router.get("/aggregations/reportingByYear", asyncHandler(movieController.getMoviesByYearWithStats));
152377

153378
/**
154-
* GET /api/movies/aggregations/reportingByDirectors
155-
*
156-
* Aggregate directors with the most movies.
157-
* Demonstrates MongoDB $unwind and $group for array aggregation.
379+
* @swagger
380+
* /api/movies/aggregations/reportingByDirectors:
381+
* get:
382+
* summary: Get directors with the most movies
383+
* description: Aggregate directors with the most movies, including their movie count and average rating. Demonstrates MongoDB $unwind and $group for array aggregation.
384+
* tags: [Movies]
385+
* parameters:
386+
* - in: query
387+
* name: limit
388+
* schema:
389+
* type: integer
390+
* default: 20
391+
* maximum: 100
392+
* description: Number of directors to return
393+
* responses:
394+
* 200:
395+
* description: Directors with the most movies
396+
* content:
397+
* application/json:
398+
* schema:
399+
* allOf:
400+
* - $ref: '#/components/schemas/SuccessResponse'
401+
* - type: object
402+
* properties:
403+
* data:
404+
* type: array
405+
* items:
406+
* type: object
407+
* properties:
408+
* director:
409+
* type: string
410+
* example: Steven Spielberg
411+
* movieCount:
412+
* type: integer
413+
* example: 25
414+
* averageRating:
415+
* type: number
416+
* example: 7.85
158417
*/
159418
router.get("/aggregations/reportingByDirectors", asyncHandler(movieController.getDirectorsWithMostMovies));
160419

0 commit comments

Comments
 (0)
⚡