Swagger UI 로컬 활용 완벽 가이드 - 오프라인 환경에서 API 개발 가속화하기

배고픈코알라·2025년 6월 27일

로컬 Swagger UI 활용의 진정한 가치: 경험자의 이야기

"마감까지 이틀밖에 남지 않았는데, 고객이 API 명세 변경을 요청했어요..."

저는 금융 프로젝트의 마지막 단계에서 이런 상황에 직면했습니다. 더 나쁜 것은, 출장 중 호텔에서 불안정한 인터넷 연결로 작업해야 했다는 점이었죠. 온라인 API 문서 도구를 사용할 수 없어 막막했지만, 로컬에서 Swagger UI를 사용하는 방법이 떠올랐습니다.

결과적으로, 로컬 Swagger UI 사용은 다음 3가지 문제를 즉시 해결해 주었습니다:

오프라인 환경에서도 완전한 API 문서를 작성하고 편집 가능
고객과의 회의 중에도 실시간으로 명세 변경 사항 반영 가능
엄격한 보안 요구사항이 있는 프로젝트에서도 안전하게 사용 가능

이 글에서는 제 실제 경험을 바탕으로 로컬 Swagger UI를 활용하는 구체적인 방법과 개발 효율성을 향상시키는 방법을 설명하겠습니다. API 개발에 참여하는 엔지니어분들께 도움이 되길 바랍니다.

단 5분 만에 시작하기! 로컬 Swagger UI 환경 설정 가이드

"복잡할 것 같다..."라고 생각하실 수 있지만, 실제로 로컬 Swagger UI 환경 설정은 놀라울 정도로 간단합니다. 다음 단계를 따라하면 약 5분 만에 설정을 완료할 수 있습니다.

1단계: Swagger UI 가져오기

가장 간단한 방법은 GitHub에서 저장소를 클론하는 것입니다:

git clone https://github.com/swagger-api/swagger-ui.git

2단계: 간단한 웹 서버 준비하기

Node.js가 설치되어 있다면, http-server를 전역으로 설치합니다:

npm install -g http-server

3단계: 서버 시작하기

Swagger UI의 배포 디렉토리로 이동하여 서버를 시작합니다:

cd swagger-ui/dist
http-server --cors

--cors 옵션은 Cross-Origin Resource Sharing을 활성화하기 위해 사용됩니다.

4단계: 브라우저로 접속하기

브라우저에서 http://localhost:8080에 접속하여 Swagger UI 인터페이스를 확인합니다.

5단계: API 명세 파일 준비하기

다음은 최소한의 Swagger 명세 파일 예시입니다(swagger.yaml로 저장):

openapi: 3.0.0
info:
  title: 샘플 API
  version: 1.0.0
paths:
  /hello:
    get:
      summary: 인사말을 반환하는 API
      responses:
        '200':
          description: 성공적인 응답
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

6단계: Swagger UI에서 명세 파일 표시하기

Swagger-UI

Swagger UI 화면 상단의 입력 상자에 로컬 명세 파일의 URL(예: http://localhost:8080/swagger.yaml)을 입력한 다음 "Explore" 버튼을 클릭합니다.

위 단계를 통해 로컬 환경에서 Swagger UI로 API 문서를 생성하고 볼 수 있습니다. 이 방법을 사용하면 인터넷 연결이 없거나 엄격한 보안 요구사항이 있는 환경에서도 API 문서를 작성하고 편집할 수 있습니다.

로컬 Swagger UI 활용 실제 사례: 내 경험에서

사례 1: 출장 중 API 명세 변경 처리하기

앞서 언급했듯이, 로컬 Swagger UI의 가치를 처음 깨달은 것은 출장 중이었습니다. 고객과의 회의에서 명세 변경을 결정했고, 그 자리에서 바로 API 문서를 업데이트해야 했습니다.

호텔 Wi-Fi가 불안정했지만, 로컬 Swagger UI 덕분에 다음과 같은 작업이 가능했습니다:

고객 요구사항에 따라 YAML 파일 편집
로컬 서버에서 변경 사항 즉시 반영
그 자리에서 고객에게 업데이트된 문서 보여주기

과정이 매끄럽게 진행되었고, "와, 이거 정말 편리하네!"라는 놀라움을 아직도 기억합니다.

사례 2: 엄격한 보안 요구사항이 있는 프로젝트에서 활용하기

또 다른 경우로, 외부 서비스 사용을 제한하는 보안 정책이 있는 금융 프로젝트에서 일한 적이 있습니다. 온라인 도구로 API 문서를 관리할 수 없었지만, 로컬 Swagger UI를 사용함으로써 다음과 같은 작업이 가능했습니다:

민감한 정보가 포함된 API 명세를 안전하게 관리
Git 저장소를 통해 팀 내에서 명세 공유
CI/CD 파이프라인과 통합하여 문서 자동 생성 및 검증

Swagger UI 기본 이해하기: API 문서의 새로운 형태

기본으로 돌아가서 Swagger UI에 대해 간략히 설명하겠습니다.

Swagger UI는 OpenAPI Specification(이전의 Swagger Specification)으로 작성된 API 정의를 시각적으로 표시하고 검증하는 도구입니다. JavaScript로 개발된 오픈 소스 프로젝트로 다음과 같은 특징이 있습니다:

시각적 API 표현: YAML/JSON으로 작성된 API 정의를 읽기 쉬운 방식으로 표시
대화형 검증: 실제 API 요청을 보내 작동을 확인 가능
문서와 테스트 통합: 명세와 테스트가 결합됨

Swagger UI의 가장 큰 매력은 "API 문서를 단순한 텍스트가 아닌 대화형 경험으로 제공하는 능력"입니다.

로컬 사용의 이점 심층 분석: 왜 오프라인으로 사용해야 할까요?

로컬 Swagger UI 사용의 이점을 더 자세히 살펴보겠습니다.

1. 보안 및 개인 정보 보호

민감한 정보 보호: 내부 API가 외부에 노출될 위험 방지
규정 준수: 엄격한 규제가 있는 산업(금융, 의료)에서 안전하게 사용 가능
IP 보호: 경쟁사에 API 설계가 유출될 위험 감소

2. 오프라인 작업의 자유

위치 독립적 개발: 이동 중이나 불안정한 연결 상태에서도 작업 가능
네트워크 독립성: 클라우드 서비스 장애에 영향받지 않음
연속성 보장: 온라인과 오프라인 간 원활한 전환

3. 성능 및 응답성

빠른 응답: 네트워크 지연이 없어 사용자 경험 향상
리소스 효율성: 로컬 리소스 최대 활용
대규모 API 정의 처리: 복잡한 API 정의도 원활하게 작동

4. 개발 프로세스와의 통합

버전 관리와의 통합: Git과 같은 VCS로 API 정의 쉽게 관리
CI/CD와의 통합: 자동 테스트 및 검증 프로세스에 쉽게 통합
팀 개발 효율성 향상: 프론트엔드와 백엔드 개발자가 동일한 명세 참조

고급 기술: 심화 로컬 Swagger UI 활용법

로컬 Swagger UI 환경을 최대한 활용하기 위한 몇 가지 고급 기술을 소개합니다.

기술 1: 커스텀 테마 적용하기

Swagger UI의 디자인을 프로젝트에 맞게 커스터마이징할 수 있습니다. swagger-ui/dist/swagger-ui.css를 편집하거나 커스텀 CSS를 추가하여 브랜드 색상에 맞는 테마를 만들 수 있습니다.

기술 2: 여러 환경 간 전환하기

개발, 테스트, 프로덕션과 같은 여러 환경의 API 정의 간에 전환하려면 다음과 같은 HTML 파일을 만들 수 있습니다:

<!DOCTYPE html>
<html>
<head>
  <title>API 문서</title>
  <link rel="stylesheet" type="text/css" href="./swagger-ui.css">
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="./swagger-ui-bundle.js"></script>
  <script>
    window.onload = function() {
      const ui = SwaggerUIBundle({
        urls: [
          {url: "specs/dev.yaml", name: "개발 환경"},
          {url: "specs/test.yaml", name: "테스트 환경"},
          {url: "specs/prod.yaml", name: "프로덕션 환경"}
        ],
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [SwaggerUIBundle.presets.apis],
      });
      window.ui = ui;
    };
  </script>
</body>
</html>

기술 3: 모의 서버와 결합하기

Swagger UI를 모의 서버와 결합하면 실제 백엔드 없이도 API 작동을 테스트할 수 있습니다. 예를 들어, swagger-ui를 json-server와 결합할 수 있습니다:

npm install -g json-server
json-server --watch mock-data.json --routes routes.json --port 3000

그런 다음 Swagger UI 정의 파일의 servers 섹션을 다음과 같이 구성합니다:

servers:
  - url: http://localhost:3000
    description: 모의 서버

기본으로 돌아가기: 효과적인 API 설계를 위한 모범 사례

Swagger UI를 최대한 활용하려면 품질 높은 API 설계가 필수적입니다. 효과적인 API 설계를 위한 모범 사례를 살펴보겠습니다.

1. 일관된 명명 규칙

엔드포인트에 복수형 명사 사용(예: /users, /products)
HTTP 메서드로 작업 표현(GET, POST, PUT, DELETE)
쿼리 매개변수와 경로 매개변수 명확히 구분

2. 적절한 HTTP 상태 코드 사용

200대: 성공(200 OK, 201 Created, 204 No Content)
400대: 클라이언트 오류(400 Bad Request, 404 Not Found)
500대: 서버 오류(500 Internal Server Error)

3. 상세한 문서화

각 엔드포인트의 목적과 사용 예시 명확히 설명
요청/응답 예시 제공
오류 케이스와 처리 방법 설명

이러한 모범 사례를 API 설계에 적용하면 Swagger UI의 가치를 최대한 활용할 수 있습니다.

다른 도구와의 비교: Apidog 선택하기

Swagger UI는 훌륭한 도구이지만, 더 통합된 API 개발 환경을 찾고 있다면 Apidog를 고려해볼 만합니다.

Apidog는 API 설계, 문서 생성, 테스트, 모의 서버 기능을 단일 플랫폼에서 제공하는 도구입니다. Swagger/OpenAPI 명세 파일을 직접 가져올 수 있으며, 복잡한 설정 없이 바로 사용할 수 있습니다.
apidog

Apidog의 주요 기능

시각적 인터페이스: 드래그 앤 드롭으로 API 설계
통합 테스트 기능: 문서와 같은 곳에서 API 테스트 수행
팀 협업: 동시 편집 및 권한 관리
아름다운 문서: 커스터마이징 가능한 공개 문서

저는 개인적으로 작은 프로젝트에는 Swagger UI를, 대규모 팀 개발 프로젝트에는 Apidog를 사용합니다. 둘 다 훌륭한 도구이므로 프로젝트 규모와 요구사항에 따라 선택하시면 됩니다.

요약: 로컬 Swagger UI로 개발 효율성 극대화하기

이 글에서는 실제 예시와 함께 로컬 환경에서 Swagger UI를 활용하는 방법을 설명했습니다.

주요 포인트 요약:

로컬 Swagger UI 사용으로 오프라인 환경과 엄격한 보안 요구사항이 있는 환경에서도 API 개발 가능
설정은 매우 간단하며, GitHub에서 클론하고 간단한 웹 서버를 시작하는 것만으로 충분
실제로는 출장 중이나 엄격한 보안 환경에서도 유연한 API 개발을 가능하게 함
기본적인 API 설계 모범 사례를 마스터하면 Swagger UI를 더 효과적으로 활용 가능
프로젝트 규모와 요구사항에 따라 Swagger UI와 Apidog 같은 도구를 함께 사용하는 것도 좋은 전략

로컬 Swagger UI 사용은 API 개발의 효율성과 품질을 크게 향상시킬 수 있습니다. 지금 바로 시도해보세요!

"이런 방식으로도 활용할 수 있겠네!"라는 아이디어가 있으시면 댓글로 공유해주세요. API 문서화 문제를 함께 해결해 나가요!

배고픈코알라

이전 포스트

[실제 경험] Claude Code와 Cursor: 일주일 사용 후 알게 된 진짜 비용 효율

다음 포스트