Add OpenAPI documentation with Swagger UI for tRPC API #49
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,72 @@ | ||||||
| 'use client'; | ||||||
|
|
||||||
| import { useEffect, useRef, useState } from 'react'; | ||||||
|
|
||||||
| export default function ApiDocsPage() { | ||||||
| const containerRef = useRef<HTMLDivElement>(null); | ||||||
| const [isLoading, setIsLoading] = useState(true); | ||||||
|
|
||||||
| useEffect(() => { | ||||||
| let mounted = true; | ||||||
|
|
||||||
| // Dynamically load Swagger UI | ||||||
| const loadSwaggerUI = async () => { | ||||||
| if (!containerRef.current) return; | ||||||
|
|
||||||
| // Check if CSS is already loaded | ||||||
| const existingLink = document.querySelector( | ||||||
| 'link[href*="swagger-ui.css"]' | ||||||
| ); | ||||||
| if (!existingLink) { | ||||||
| // Load CSS from the installed package | ||||||
| const link = document.createElement('link'); | ||||||
| link.rel = 'stylesheet'; | ||||||
| link.href = | ||||||
| '/_next/static/css/swagger-ui.css'; | ||||||
| document.head.appendChild(link); | ||||||
| } | ||||||
|
|
||||||
| try { | ||||||
| // Load and initialize Swagger UI | ||||||
| const SwaggerUIBundle = ( | ||||||
| await import('swagger-ui-dist/swagger-ui-es-bundle.js') | ||||||
| ).default; | ||||||
|
|
||||||
| if (mounted && containerRef.current) { | ||||||
| SwaggerUIBundle({ | ||||||
| domNode: containerRef.current, | ||||||
| url: '/api/docs/openapi.json', | ||||||
| deepLinking: true, | ||||||
| }); | ||||||
| setIsLoading(false); | ||||||
| } | ||||||
| } catch (error) { | ||||||
| console.error('Failed to load Swagger UI:', error); | ||||||
| setIsLoading(false); | ||||||
|
Comment on lines
+43
to
+45
There was a problem hiding this comment. The error handling logs to console but doesn't display an error message to the user. If Swagger UI fails to load, users will see the loading message disappear but get no indication of what went wrong. Consider showing an error message to help users understand when the API documentation fails to load: const [error, setError] = useState<string | null>(null);
// In catch block:
setError('Failed to load API documentation. Please refresh the page.');
// In JSX:
{error && <div className="text-red-600 p-8">{error}</div>} |
||||||
| } | ||||||
| }; | ||||||
|
|
||||||
| loadSwaggerUI(); | ||||||
|
|
||||||
| return () => { | ||||||
| mounted = false; | ||||||
| }; | ||||||
| }, []); | ||||||
|
|
||||||
| return ( | ||||||
| <div className="min-h-screen bg-white"> | ||||||
| {isLoading && ( | ||||||
| <div className="flex items-center justify-center p-8"> | ||||||
| <p>Loading API documentation...</p> | ||||||
| </div> | ||||||
| )} | ||||||
| <div ref={containerRef} /> | ||||||
| <style jsx global>{` | ||||||
| /* Swagger UI CSS is loaded via the JS bundle */ | ||||||
|
There was a problem hiding this comment. The comment on line 65 mentions "Swagger UI CSS is loaded via the JS bundle", but this is misleading. The CSS is actually being loaded dynamically by manually creating a link element (lines 22-26), not through the JS bundle import. The global styles defined here only add minor adjustments to the Swagger UI styling. Consider updating the comment to be more accurate: /* Additional styling adjustments for Swagger UI */
Suggested change
|
||||||
| .swagger-ui .info { | ||||||
| margin: 50px 0; | ||||||
| } | ||||||
| `}</style> | ||||||
| </div> | ||||||
| ); | ||||||
| } | ||||||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| import { NextResponse } from 'next/server'; | ||
| import { openApiDocument } from '@repo/api'; | ||
|
|
||
| export async function GET() { | ||
| return NextResponse.json(openApiDocument); | ||
| } | ||
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,4 @@ | ||
| export { appRouter } from './root'; | ||
| export type { AppRouter } from './root'; | ||
| export { createContext } from './context'; | ||
| export { openApiDocument } from './openapi'; |
Oops, something went wrong.
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The CSS file path
/_next/static/css/swagger-ui.cssappears to be incorrect. Theswagger-ui-distpackage provides CSS files that should be accessed through the node_modules path or copied to the public directory. Next.js won't automatically serve CSS fromswagger-ui-distat this path.Consider using the CSS directly from the package using an import statement or copying the CSS file to the public directory and referencing it properly. For example:
Or serve it from a public asset path if you copy
swagger-ui.cssfrom the package to your public directory.