feat: ✨ add openapi documentation #101
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- 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
There was a problem hiding this comment.
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-docsand 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);
| * application/problem+json: | ||
| * schema: | ||
| * $ref: '#/components/schemas/HttpMockResponse' | ||
| */ | ||
| router.use('/:httpCode/:message?', (req, res) => { |
There was a problem hiding this comment.
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 uses AI. Check for mistakes.
| * $ref: '#/components/schemas/CustomResponseData' | ||
| * 404: | ||
| * description: Not found | ||
| */ | ||
| router.use('/:identifier', cacheMiddleware, async (req, res, next) => { |
There was a problem hiding this comment.
8000Switch 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) => { |
Copilot uses AI. Check for mistakes.
|
Hey @Ovi Copilot's review lists two things that I didn't touch. What do you want to do here? |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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:
Motivation
Changes Made
1. JSDoc Comments
src/routes/(e.g.,user.js,product.js, etc.).src/models/openapi-schemas/for better clarity and type safety.2. Scalar API Reference Integration
/api-docs, for interactive OpenAPI documentation.src/middleware/openapi.jsto dynamically load 8000 and serve the Scalar UI.src/routes/api-docs.jsto route documentation requests to Scalar and the OpenAPI spec.Testing
/api-docsand/api-docs/openapi.jsonendpoints serve the correct content.