Next.js 15가 24년 12월에 stable 버전으로 출시되었지만,
나는 Next.js 14. 즉 React 18 버전에 갇혀있었다.
15는 PWA도 기본 지원이 되고...
터보팩도 안정화에 성능이 향상 되었으며...
내가 궁금한 업데이트가 너무 많았다.
들뜬 마음으로 바로 설치하려 했으나
기존에 사용하고 있던 라이브러리 호환이 제대로 되지 않아서
무력하게 14로 돌아갔다.
부작용 라이브러리 중 하나 swagger-ui-react
회사에서도 개인용으로도 스웨거를 정말 애용하는 편이다.
API를 빠르게 체킹하는데 UI도 보기편하고 너무 유용하다.
단순 코드 기반이 리액트라서 swagger-ui-react를 써왔더니
react 19로는 업데이트가 불가하다고 배신을 하더라.
그렇다고 대응이 빨랐나?
24년 12월 부터 지금까지 반년은 기다린것 같다.
정말 답답해서 해당 라이브러리 깃 이슈에도 등록을 했다.
https://github.com/swagger-api/swagger-ui/issues/10243
나말고도 역시나 문제인 사람들이 많았는지
나의 이슈에 공감이 꽤나 있었다.
Next.js 15 마이너 버전은 계속 나오고...
15.1 → 15.2 → 15.3 자꾸 블로그가 올라오는데
이깟 스웨거 하나 때문에
경험은 물론, 기술 트렌드를 따라가지 못하고 있는 느낌이었다.
결심했다. 순수 swgger-ui를 이용해보자.
React 19에 의하여 업데이트가 자꾸 차단 당할바에
파생된 스웨거 swagger-ui-react가 아닌
순수 스웨거 swagger-ui-dist를 이용하기로 결심했다.
리액트 호환 쯤이야 내가 조금 귀찮으면 되는거고
무엇보다 6개월을 기다렸는데 해결에 대한 회신도 없어서
앞으로 React 20, 21, 22 메이저 버전이 업데이트 될때도
계속해서 뒤처질 것으로 예상이 되어
순수 스웨거를 이용하기로 결심했다.
마이그레이션 코드
import { createSwaggerSpec } from 'next-swagger-doc';
export async function getApiDocs() {
const spec = createSwaggerSpec({
apiFolder: 'src/app/<YOUR_ADDRESS>/apis',
definition: {
openapi: '3.0.0',
info: {
title: 'API Documentation',
version: '1.0',
},
},
});
return spec;
}import { getApiDocs } from '@/src/<YOUR_ADDRESS>';
import PageContent from './page-content';
import { notFound } from 'next/navigation';
export default async function Page() {
if (process.env.NODE_ENV !== 'development') notFound();
const spec = await getApiDocs();
return <PageContent spec={spec} />;
}'use client';
import { useEffect, useRef } from 'react';
import { SwaggerUIBundle } from 'swagger-ui-dist';
import 'swagger-ui-dist/swagger-ui.css';
export default function PageContent({ spec }: { spec: any }) {
const swaggerRef = useRef<HTMLDivElement>(null);
useEffect(() => {
if (!swaggerRef.current || !spec) return;
SwaggerUIBundle({
domNode: swaggerRef.current,
spec,
});
}, []);
return (
<div
className='swagger-ui-wrapper'
ref={swaggerRef}
/>
);
}내가 올려놓았던 깃 이슈에도 답변을 달았다.
같은 상황에 처한 분들이라면
이 글이 도움되기를 바라며
swagger-ui-react에 의존하지말고
swagger-ui-dist로 당장 마이그레이션 하는 것을 추천한다.
채팅 문의