feat: ✨ add openapi documentation by ueberBrot · Pull Request #101 · Ovi/DummyJSON

ueberBrot · 2025-05-15T16:45:59Z

While seeking test data recently, I discovered this project and found it to be a valuable resource. I noticed the absence of an OpenAPI specification, which is often beneficial for API documentation and client integration. Believing this would be a valuable addition, I've developed an OpenAPI specification for the project's API and added an interactive API documentation UI. This pull request introduces these enhancements.

Summary

This PR significantly improves the project’s documentation by:

Adding JSDoc comments across routes and creating model schema files.
Integrating Scalar’s API Reference UI for interactive OpenAPI documentation.

Motivation

Improved Developer Experience: JSDoc comments and interactive docs make onboarding and collaboration easier.
API Consumer Support: Scalar UI provides a user-friendly way for external developers to explore and test the API.
Maintainability: Well-documented code and schemas reduce the risk of misunderstandings and bugs.

Changes Made

1. JSDoc Comments

Added comprehensive JSDoc comments to all major route handlers in src/routes/ (e.g., user.js, product.js, etc.).
Documented model schemas in src/models/openapi-schemas/ for better clarity and type safety.
Ensured consistency and completeness in parameter, return type, and function descriptions.

2. Scalar API Reference Integration

Added Scalar’s API Reference UI, accessible at /api-docs, for interactive OpenAPI documentation.
Created/updated src/middleware/openapi.js to dynamically load and serve the Scalar UI.
Updated src/routes/api-docs.js to route documentation requests to Scalar and the OpenAPI spec.

Testing

Verified JSDoc rendering in IDEs and with documentation tools.
Confirmed /api-docs and /api-docs/openapi.json endpoints serve the correct content.
Ensured no breaking changes to existing API routes or middleware.

- add openapi documentation for all relevant routes - add openapi documentation for models - add scalar for api reference in the browser - add openapi.json file route

Copilot

Pull Request Overview

This PR adds a full OpenAPI 3.1.0 specification and interactive API documentation UI via Scalar.

Introduces JSDoc comments on all route handlers to generate OpenAPI docs.
Creates model schema files under src/models/openapi-schemas/ for each resource.
Integrates Scalar’s API Reference UI at /api-docs and serves the spec at /api-docs/openapi.json.

Reviewed Changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/routes/http.js	Add OpenAPI JSDoc for the HttpMock route
src/routes/custom-response.js	Add OpenAPI JSDoc for custom-response generation and retrieval
src/routes/comment.js	Add OpenAPI JSDoc for comment endpoints
src/routes/cart.js	Add OpenAPI JSDoc for cart endpoints
src/routes/auth.js	Add OpenAPI JSDoc for authentication endpoints
src/routes/api-docs.js	New router to serve OpenAPI spec and interactive UI
src/models/openapi-schemas/*.js	Add component schemas for all resources
src/middleware/openapi.js	Initialize and serve the Scalar UI and OpenAPI JSON
package.json	Add `@scalar/express-api-reference` and `swagger-jsdoc` deps
README.md	Document links to the new OpenAPI spec and interactive UI

Comments suppressed due to low confidence (1)

src/routes/api-docs.js:5

Consider adding tests to verify that the /api-docs/openapi.json endpoint returns a valid OpenAPI JSON and the interactive UI route serves the expected content.

router.get('/openapi.json', serveOpenAPISpec);

Copilot · 2025-06-17T17:58:36Z

src/routes/http.js

+ *             schema:
+ *               $ref: '#/components/schemas/HttpMockResponse'
+ */
 router.use('/:httpCode/:message?', (req, res) => {


Consider using router.get instead of router.use to restrict this handler to GET requests and align with the OpenAPI documentation.

Suggested change

router.use('/:httpCode/:message?', (req, res) => {

router.get('/:httpCode/:message?', (req, res) => {

Copilot · 2025-06-17T17:58:37Z

src/routes/custom-response.js

+ *       404:
+ *         description: Not found
+ */
 router.use('/:identifier', cacheMiddleware, async (req, res, next) => {


Switch to router.get for this GET-only endpoint to better match HTTP semantics and the OpenAPI spec.

Suggested change

router.use('/:identifier', cacheMiddleware, async (req, res, next) => {

router.get('/:identifier', cacheMiddleware, async (req, res, next) => {

ueberBrot · 2025-06-22T17:51:39Z

Hey @Ovi Copilot's review lists two things that I didn't touch. What do you want to do here?

Ovi

Thank you, @ueberBrot! 💙
You've done an excellent job with this PR!

This is just my initial review. I’ll go through more files as I get the time. No rush on the changes; please take your time.

P.S. This PR is open for voluntary review by anyone in the community — feel free to jump in!

Ovi · 2025-06-28T19:42:37Z

src/models/openapi-schemas/auth.js

+ *       required:
+ *         - id
+ *         - username
+ *         - email
+ *         - firstName
+ *         - lastName


Please add gender and image

Ovi · 2025-06-28T19:55:04Z

src/models/openapi-schemas/auth.js

+ *         - accessToken
+ *         - refreshToken
+ */
+


Please add Invalid Credentials Response

Ovi · 2025-06-28T19:57:59Z

src/models/openapi-schemas/cart.js

+ *         thumbnail:
+ *           type: string
+ *           description: Product thumbnail URL
+ *           example: "https://cdn.dummyjson.com/products/images/vehicle/Charger%20SXT%20RWD/thumbnail.png"


Please use updated url:
https://cdn.dummyjson.com/product-images/.../...

Update: I just found that cart still has old urls, I will update these soon.

Ovi · 2025-06-28T19:58:58Z

src/models/openapi-schemas/product.js

+ *         thumbnail:
+ *           type: string
+ *           description: URL to the product thumbnail image
+ *           example: "https://cdn.dummyjson.com/products/images/beauty/Essence%20Mascara%20Lash%20Princess/thumbnail.png"


Please use updated url:
https://cdn.dummyjson.com/product-images/.../...

Ovi · 2025-06-28T19:59:04Z

src/models/openapi-schemas/product.js

+ *           description: URLs to product images
+ *           items:
+ *             type: string
+ *           example: ["https://cdn.dummyjson.com/products/images/beauty/Essence%20Mascara%20Lash%20Princess/1.png"]


Please use updated url:
https://cdn.dummyjson.com/product-images/.../...

Ovi · 2025-06-28T20:00:48Z

src/models/openapi-schemas/test.js

+ *       properties:
+ *         status:
+ *           type: string
+ *           description: Status of the server


Suggested change

* description: Status of the server

* description: Test route

Ovi · 2025-06-28T20:01:57Z

src/models/openapi-schemas/user.js

+ *       properties:
+ *         id:
+ *           type: integer
+ *           description: Unique identifier for the user
+ *           example: 1
+ *         firstName:
+ *           type: string
+ *           example: "Terry"
+ *         lastName:
+ *           type: string
+ *           example: "Medhurst"
+ *         maidenName:
+ *           type: string
+ *           example: "Smitham"
+ *         age:
+ *           type: integer
+ *           example: 50
+ *         gender:
+ *           type: string
+ *           example: "male"
+ *         email:
+ *           type: string
+ *           example: "atuny0@sohu.com"
+ *         phone:
+ *           type: string
+ *           example: "+63 791 675 8914"
+ *         username:
+ *           type: string
+ *           example: "atuny0"
+ *         password:
+ *           type: string
+ *           example: "9uQFF1Lh"
+ *         birthDate:
+ *           type: string
+ *           example: "2000-12-25"
+ *         image:
+ *           type: string
+ *           example: "https://robohash.org/hicveldicta.png"
+ *         bloodGroup:
+ *           type: string
+ *           example: "A−"
+ *         height:
+ *           type: integer
+ *           example: 189
+ *         weight:
+ *           type: number
+ *           example: 75.4
+ *         eyeColor:
+ *           type: string
+ *           example: "Green"
+ *         hair:
+ *           type: object
+ *           properties:
+ *             color:
+ *               type: string
+ *               example: "Black"
+ *             type:
+ *               type: string
+ *               example: "Strands"
+ *         domain:
+ *           type: string
+ *           example: "slashdot.org"
+ *         ip:
+ *           type: string
+ *           example: "117.29.86.254"
+ *         address:
+ *           type: object
+ *           properties:
+ *             address:
+ *               type: string
+ *               example: "1745 T Street Southeast"
+ *             city:
+ *               type: string
+ *               example: "Washington"
+ *             coordinates:
+ *               type: object
+ *               properties:
+ *                 lat:
+ *                   type: number
+ *                   example: 38.867033
+ *                 lng:
+ *                   type: number
+ *                   example: -76.979235
+ *             postalCode:
+ *               type: string
+ *               example: "20020"
+ *             state:
+ *               type: string
+ *               example: "DC"
+ *         macAddress:
+ *           type: string
+ *           example: "13:69:BA:56:A3:74"
+ *         university:
+ *           type: string
+ *           example: "Capitol University"
+ *         bank:
+ *           type: object
+ *           properties:
+ *             cardExpire:
+ *               type: string
+ *               example: "06/22"
+ *             cardNumber:
+ *               type: string
+ *               example: "50380955204220685"
+ *             cardType:
+ *               type: string
+ *               example: "maestro"
+ *             currency:
+ *               type: string
+ *               example: "Peso"
+ *             iban:
+ *               type: string
+ *               example: "NO17 0695 2754 967"
+ *         company:
+ *           type: object
+ *           properties:
+ *             address:
+ *               type: object
+ *               properties:
+ *                 address:
+ *                   type: string
+ *                   example: "629 Debbie Drive"
+ *                 city:
+ *                   type: string
+ *                   example: "Nashville"
+ *                 coordinates:
+ *                   type: object
+ *                   properties:
+ *                     lat:
+ *                       type: number
+ *                       example: 36.208114
+ *                     lng:
+ *                       type: number
+ *                       example: -86.586211
+ *                 postalCode:
+ *                   type: string
+ *                   example: "37076"
+ *                 state:
+ *                   type: string
+ *                   example: "TN"
+ *             department:
+ *               type: string
+ *               example: "Marketing"
+ *             name:
+ *               type: string
+ *               example: "Blanda-O'Keefe"
+ *             title:
+ *               type: string
+ *               example: "Help Desk Operator"
+ *         ein:
+ *           type: string
+ *           example: "20-9487066"
+ *         ssn:
+ *           type: string
+ *           example: "661-64-2976"
+ *         userAgent:
+ *           type: string
+ *           example: "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36"


Please use updated user details, e.g.: User 1

Ovi · 2025-06-28T20:02:20Z

src/models/openapi-schemas/user.js

+ *         - weight
+ *         - eyeColor
+ *         - hair
+ *         - domain


Suggested change

* - domain

Ovi · 2025-06-28T20:02:38Z

src/models/openapi-schemas/user.js

+ *         - company
+ *         - ein
+ *         - ssn
+ *         - userAgent


Suggested change

* - userAgent

* - userAgent

* - crypto

Ovi · 2025-06-28T20:03:20Z

src/models/openapi-schemas/user.js

+ *         id: 1
+ *         firstName: "Terry"
+ *         lastName: "Medhurst"
+ *         maidenName: "Smitham"
+ *         age: 50
+ *         gender: "male"
+ *         email: "atuny0@sohu.com"
+ *         phone: "+63 791 675 8914"
+ *         username: "atuny0"
+ *         password: "9uQFF1Lh"
+ *         birthDate: "2000-12-25"
+ *         image: "https://robohash.org/hicveldicta.png"
+ *         bloodGroup: "A−"
+ *         height: 189
+ *         weight: 75.4
+ *         eyeColor: "Green"
+ *         hair:
+ *           color: "Black"
+ *           type: "Strands"
+ *         domain: "slashdot.org"
+ *         ip: "117.29.86.254"
+ *         address:
+ *           address: "1745 T Street Southeast"
+ *           city: "Washington"
+ *           coordinates:
+ *             lat: 38.867033
+ *             lng: -76.979235
+ *           postalCode: "20020"
+ *           state: "DC"
+ *         macAddress: "13:69:BA:56:A3:74"
+ *         university: "Capitol University"
+ *         bank:
+ *           cardExpire: "06/22"
+ *           cardNumber: "50380955204220685"
+ *           cardType: "maestro"
+ *           currency: "Peso"
+ *           iban: "NO17 0695 2754 967"
+ *         company:
+ *           address:
+ *             address: "629 Debbie Drive"
+ *             city: "Nashville"
+ *             coordinates:
+ *               lat: 36.208114
+ *               lng: -86.586211
+ *             postalCode: "37076"
+ *             state: "TN"
+ *           department: "Marketing"
+ *           name: "Blanda-O'Keefe"
+ *           title: "Help Desk Operator"
+ *         ein: "20-9487066"
+ *         ssn: "661-64-2976"
+ *         userAgent: "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36"


Please use updated user details, e.g.: User 1

ueberBrot and others added 2 commits May 13, 2025 20:18

feat: ✨ add openapi documentation

915f37f

- add openapi documentation for all relevant routes - add openapi documentation for models - add scalar for api reference in the browser - add openapi.json file route

Merge branch 'Ovi:master' into feature/openapi-documentation

81969f0

Ovi requested a review from Copilot June 17, 2025 17:56

Copilot AI reviewed Jun 17, 2025

View reviewed changes

Ovi requested changes Jun 28, 2025

View reviewed changes

	router.use('/:httpCode/:message?', (req, res) => {
	router.get('/:httpCode/:message?', (req, res) => {

	router.use('/:identifier', cacheMiddleware, async (req, res, next) => {
	router.get('/:identifier', cacheMiddleware, async (req, res, next) => {

	* description: Status of the server
	* description: Test route

Uh oh!

Conversation

ueberBrot commented May 15, 2025

Summary

Motivation

Changes Made

1. JSDoc Comments

2. Scalar API Reference Integration

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

ueberBrot commented Jun 22, 2025

Uh oh!

Ovi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants