API 명세서 및 Swagger 활용

API 명세서는 애플리케이션 프로그래밍 인터페이스(API)의 기능, 사용 방법, 요구 사항을 기술한 공식 문서이다. 이 문서는 API가 제공하는 엔드포인트, 허용되는 HTTP 메서드, 요청과 응답의 형식, 필요한 인증 방식, 가능한 에러 코드 등을 상세히 정의한다. 본질적으로 API의 계약서 또는 사용 설명서 역할을 하여, 개발자들이 API를 어떻게 호출하고 어떤 결과를 기대할 수 있는지 이해할 수 있도록 돕는다.

API 명세서의 주요 역할은 명확한 커뮤니케이션과 개발 생산성 향상이다. API 제공자와 소비자(클라이언트 개발자) 사이에 오해와 불일치를 방지하는 단일한 정보 출처를 제공한다. 이를 통해 프론트엔드와 백엔드 팀이 독립적으로 병렬 개발을 진행할 수 있으며, 통합 과정에서 발생할 수 있는 문제를 사전에 줄인다. 또한, 명세서는 새로 합류하는 개발자에게 API의 구조와 규칙을 빠르게 전달하는 온보딩 도구로서도 기능한다.

명세서는 API의 수명 주기 전반에 걸쳐 중요한 기준점이 된다. 설계 단계에서는 요구사항을 구체화하고 검토하는 도구로, 구현 단계에서는 개발의 청사진으로, 배포 후에는 공식적인 참조 문서 및 테스트의 기반으로 활용된다. 잘 작성된 명세서는 API의 버전 관리, 변경 로그 기록, 하위 호환성 유지에도 기여한다.

API 명세서는 개발 팀 내외부의 효율적인 협업을 가능하게 합니다. 명확한 명세서가 존재하면 프론트엔드와 백엔드 개발자가 동시에 병렬 작업을 진행할 수 있습니다. 백엔드 API가 실제로 구현되기 전에도 프론트엔드 개발자는 명세서를 바탕으로 모의 객체(Mock)를 생성하여 통합을 테스트할 수 있습니다. 이는 개발 생산성을 크게 향상시키고 프로젝트 일정을 단축하는 핵심 요소입니다.

또한 명세서는 API의 공식적인 계약서 역할을 하여 오해와 불일치를 방지합니다. 모든 엔드포인트, HTTP 메서드, 요청/응답 형식, 상태 코드가 문서화되므로, 클라이언트 개발자는 API를 정확히 어떻게 사용해야 하는지 알 수 있습니다. 이는 통합 과정에서 발생할 수 있는 수많은 커뮤니케이션 오류와 버그를 사전에 차단합니다.

명세서는 API의 수명 주기 전반에 걸쳐 유용합니다. 개발 단계에서는 설계 가이드 역할을 하며, 테스트 단계에서는 자동화된 테스트 케이스 생성의 기준이 됩니다. API가 배포된 후에는 최종 사용자(다른 개발자)를 위한 가장 정확한 사용 설명서가 되어, 학습 곡선을 낮추고 API 온보딩 시간을 줄입니다. 잘 작성된 명세서는 API의 유지보수성과 확장성을 보장하는 기반이 됩니다.

다음 표는 API 명세서가 제공하는 주요 이점을 요약한 것입니다.

OpenAPI Specification(OAS)은 RESTful API를 설명하기 위한 표준화된, 프로그래밍 언어에 구애받지 않는 인터페이스 설명 형식이다. 이 명세는 API의 구조를 이해할 수 있는 기계가 읽을 수 있는 형식으로 정의하여, 인간과 컴퓨터 모두가 소스 코드나 문서에 직접 접근하지 않고도 서비스의 기능을 발견하고 이해할 수 있게 한다. OAS는 Swagger 프로젝트에서 발전했으며, 현재는 Linux Foundation 산하의 OpenAPI Initiative(OAI)에서 관리하는 개방형 표준이다.

OAS 문서는 YAML 또는 JSON 형식으로 작성되며, API의 모든 측면을 구조적으로 정의한다. 핵심 구성 요소는 다음과 같다.

이 명세를 통해 API의 엔드포인트, 필요한 요청 매개변수, 예상 응답 형식, 인증 방법, 가능한 에러 코드 등을 상세히 기술할 수 있다. 표준화된 형식이기 때문에, OAS 파일을 활용한 다양한 도구 생태계가 구축되어 있다. 이를 통해 API 문서의 자동 생성, 클라이언트 및 서버 스텁 코드 생성, 상호작용형 테스트, 심지어 API 설계 검증까지 가능해진다.

Swagger는 원래 SmartBear Software가 개발한 API 설계, 문서화, 테스트를 위한 도구 모음의 이름이었다. 여기에는 Swagger Editor, Swagger UI, Swagger Codegen 등의 도구가 포함되었다. 2015년, Swagger의 사양(Specification)이 Linux Foundation의 산하 조직인 OpenAPI Initiative(OAI)에 기여되면서 공식 표준이 되었다. 이 표준화된 사양의 이름이 OpenAPI Specification(OAS)이다.

따라서 현재는 "Swagger"와 "OpenAPI"라는 용어가 명확히 구분되어 사용된다. OpenAPI는 API를 설명하는 표준 형식, 즉 사양(Specification) 자체를 가리킨다. 반면 Swagger는 그 OpenAPI 사양을 구현하고 활용하는 도구들의 집합을 의미한다. 간단히 비유하면, OpenAPI는 HTML 표준이고, Swagger는 그 표준을 지원하는 웹 브라우저나 개발 도구라고 볼 수 있다.

이 관계는 역사적 경로 때문에 혼란을 줄 수 있다. 초기에는 Swagger 사양이 사실상의 표준 역할을 했으며, 이후 공식 표준화 과정을 거쳐 OpenAPI 사양이 되었다. 결과적으로 Swagger 도구들은 OpenAPI 사양의 가장 대표적인 구현체가 되었다. 예를 들어, Swagger UI는 OpenAPI 형식으로 작성된 명세 파일(openapi.yaml 또는 openapi.json)을 읽어 대화형 문서를 생성한다.

다음 표는 두 용어의 핵심 차이를 정리한 것이다.

현재 Swagger 도구의 공식 문서와 커뮤니티에서는 "Swagger"를 도구군을 지칭할 때, "OpenAPI"를 사양을 지칭할 때 사용하는 것을 권장한다. 예를 들어, "Swagger로 API 문서를 만들었다"보다는 "OpenAPI 명세를 작성하고 Swagger UI로 문서화했다"라고 표현하는 것이 더 정확하다.

Swagger Editor는 OpenAPI Specification을 준수하는 API 명세서를 작성, 편집 및 검증하기 위한 브라우저 기반의 시각적 도구이다. 주로 YAML 또는 JSON 형식으로 명세를 작성하며, 실시간으로 문법 검사와 스펙 유효성 검증을 제공한다. 이를 통해 개발자는 오류를 즉시 확인하고 수정할 수 있어, 정확하고 일관된 명세서 작성을 돕는다. Editor는 온라인 버전과 로컬 설치형 버전 모두 사용 가능하다.

편집기의 주요 화면은 일반적으로 왼쪽에 코드 편집 영역, 오른쪽에 실시간 렌더링된 Swagger UI 문서 미리보기 영역으로 구성된다. 사용자는 편집 영역에서 openapi, info, paths, components 등의 최상위 필드를 정의한다. 특히 paths 섹션에서는 각 API 엔드포인트의 경로, 지원하는 HTTP 메서드(GET, POST 등), 매개변수, 요청 본문, 가능한 응답 코드와 형식을 상세히 기술한다. Editor는 자동 완성과 구문 강조 기능을 제공하여 작성 효율을 높인다.

작성 과정에서 일반적으로 다음 단계를 따른다.

1. OpenAPI 버전(openapi: 3.0.0)과 API 기본 정보(info)를 정의한다.

2. 서버 URL(servers)을 명시한다.

3. 모든 API 경로를 paths 아래에 나열하고, 각 경로별로 작업을 정의한다.

4. 재사용 가능한 스키마(데이터 모델), 매개변수, 응답 등을 components 섹션에 정의하여 참조한다.

편집기가 제공하는 실시간 검증은 필수 필드 누락, 데이터 타입 불일치, 참조 오류 등 다양한 문제를 강조 표시하여 사용자에게 알린다. 이는 명세서의 품질과 상호운용성을 보장하는 데 핵심적인 역할을 한다. 작성이 완료된 명세 파일(openapi.yaml 또는 openapi.json)은 Swagger UI나 Swagger Codegen 등 다른 Swagger 도구군에서 바로 사용할 수 있다.

Swagger UI는 OpenAPI Specification으로 작성된 API 명세서를 시각적이고 상호작용 가능한 웹 문서로 변환해주는 도구이다. 이 도구는 명세 파일(일반적으로 openapi.yaml 또는 openapi.json)을 입력받아 자동으로 HTML 기반의 문서 페이지를 생성한다. 생성된 페이지에는 API의 모든 엔드포인트, HTTP 메서드, 요청 파라미터, 요청/응답 형식 등이 체계적으로 정리되어 표시된다.

가장 큰 장점은 문서를 읽는 개발자가 브라우저 내에서 직접 API를 호출하고 테스트할 수 있다는 점이다. 각 엔드포인트 옆에 있는 'Try it out' 버튼을 클릭하면, 필요한 파라미터를 입력할 수 있는 폼이 나타나고 'Execute' 버튼으로 실제 요청을 전송할 수 있다. 그러면 서버로부터의 실제 HTTP 응답 코드, 응답 헤더, 응답 본문(JSON 등)을 즉시 확인할 수 있다. 이는 API 문서화와 API 테스트를 하나의 도구로 통합한 효과를 제공한다.

Swagger UI를 프로젝트에 통합하는 방법은 다양하다. 가장 일반적인 방법은 Node.js 패키지(swagger-ui-express 또는 swagger-ui-dist)를 사용하거나, Docker 이미지를 활용하여 독립 실행형 서비스로 띄우는 것이다. 또한, CI/CD 파이프라인에 통합하여 API 명세가 변경될 때마다 자동으로 최신 문서를 배포하도록 구성할 수 있다.

이러한 기능들은 API 소비자(클라이언트 개발자)가 API를 빠르게 이해하고 통합하는 과정을 크게 단순화하며, API 제공자 역시 문서 유지 관리 부담을 줄이고 품질을 높이는 데 기여한다.

Swagger Codegen은 OpenAPI 명세서를 기반으로 서버 스텁 코드, 클라이언트 SDK, API 문서 등을 다양한 프로그래밍 언어와 프레임워크에 맞춰 자동으로 생성해주는 도구이다. 이 도구는 API First 설계 접근법의 핵심 요소로, 명세서를 단순한 문서가 아닌 실행 가능한 개발의 출발점으로 전환한다.

Swagger Codegen은 명세서 파일(openapi.yaml 또는 openapi.json)을 입력으로 받아, 지정된 언어의 템플릿을 적용하여 소스 코드를 생성한다. 지원하는 출력물의 종류는 주로 서버 코드와 클라이언트 코드로 나뉜다. 서버 코드 생성 시에는 스프링 부트, Node.js, 플라스크, 장고 등 다양한 백엔드 프레임워크에 맞는 인터페이스(라우트, 컨트롤러 스켈레톤)와 데이터 모델을 만들어준다. 클라이언트 SDK 생성 시에는 자바, 파이썬, 자바스크립트, C#, 고 등의 언어로 API를 호출할 수 있는 라이브러리를 생성하여, 프론트엔드나 다른 서비스에서의 통합 작업을 크게 단순화한다.

사용 방법은 명령줄 인터페이스(CLI), Maven/Gradle 플러그인, 또는 온라인 생성기를 통해 접근할 수 있다. 일반적인 CLI 사용 예는 다음과 같다.

```bash

java -jar swagger-codegen-cli.jar generate \

-i openapi.yaml \

-l spring \

-o ./generated-server

```

이 명령은 openapi.yaml 파일을 읽어 스프링 프레임워크용 서버 코드를 ./generated-server 디렉토리에 생성한다. 생성 과정에서 사용자는 템플릿을 커스터마이즈하거나, 특정 설정을 위한 JSON 파일을 제공하여 출력 결과를 세부적으로 조정할 수 있다[3].

이러한 자동 생성의 가장 큰 장점은 개발 생산성 향상과 일관성 유지이다. API 명세서가 변경되면 Codegen을 다시 실행하여 관련 코드를 빠르게 갱신할 수 있어, 문서와 실제 구현 사이의 불일치를 방지한다. 다만, 생성된 코드는 보통 기본적인 구조만 제공하므로, 비즈니스 로직은 개발자가 직접 구현해야 한다. 또한, 특정 프레임워크나 복잡한 사용 사례에 맞지 않는 표준적인 코드를 생성할 수 있으므로, 생성 결과를 검토하고 필요한 부분을 수정하는 작업이 필요하다.

엔드포인트는 API가 제공하는 특정 자원이나 기능에 접근할 수 있는 고유한 URL 경로이다. 명확한 엔드포인트 설계는 자원 지향 설계(RESTful) 원칙을 따르는 것이 일반적이다. 엔드포인트는 복수형 명사를 사용하여 컬렉션을 나타내고(예: /users), 특정 항목은 경로 파라미터를 통해 식별한다(예: /users/{id}). 계층적 관계를 표현할 때는 중첩된 경로를 사용할 수 있으나, 과도한 중첩은 피하는 것이 좋다.

HTTP 메서드는 해당 엔드포인트에서 수행할 연산의 유형을 정의한다. 주요 메서드와 그 역할은 다음과 같다.

엔드포인트와 HTTP 메서드의 조합은 멱등성과 안전성을 고려하여 설계한다. GET 메서드는 항상 안전하고 멱등적이어야 하며, 서버의 상태를 변경하지 않는다. PUT과 DELETE는 멱등적 연산으로, 동일한 요청을 여러 번 보내도 한 번 실행한 효과와 동일해야 한다. 반면 POST는 일반적으로 멱등성이 보장되지 않는다. 이러한 특성을 명세서에 명시하면 API 사용자의 이해를 돕고 오용을 방지할 수 있다.

요청과 응답의 형식을 명확히 정의하고, 그 안에서 사용되는 데이터 구조를 체계적으로 설계하는 것은 API 명세서의 핵심 요소이다. 이는 클라이언트와 서버 간의 데이터 교환 계약을 구체화하여 오류와 불일치를 방지한다.

요청 형식 정의에는 사용되는 HTTP 메서드 (GET, POST, PUT, DELETE 등)와 함께, 필요한 쿼리 파라미터, 경로 변수, HTTP 헤더를 상세히 기술한다. 특히 POST나 PUT 메서드와 함께 전송되는 요청 본문의 형식은 반드시 명시해야 한다. 이는 주로 JSON 또는 XML 형식을 따르며, 명세서는 해당 본문의 스키마(필드명, 데이터 타입, 필수 여부, 설명, 제약 조건 등)를 정의한다. 예를 들어, 사용자 생성 API의 요청 본문은 username(문자열, 필수), email(문자열, 필수, 이메일 형식), age(정수, 선택) 같은 필드로 구성될 수 있다.

응답 형식 설계는 성공과 실패 경우를 모두 포함한다. 각 HTTP 상태 코드(예: 200 OK, 201 Created, 400 Bad Request, 404 Not Found)별로 클라이언트가 기대할 수 있는 응답 본문의 구조를 정의한다. 성공적인 응답의 데이터 모델은 일관성을 유지해야 하며, 중첩된 객체나 배열을 포함할 수 있다. 데이터 모델 설계 시에는 재사용 가능한 컴포넌트(스키마 객체)를 정의하여 여러 엔드포인트에서 참조하는 것이 효율적이다. 이는 OpenAPI Specification에서 components/schemas 섹션을 활용하여 구현한다.

효과적인 데이터 모델 설계는 실제 비즈니스 도메인을 정확히 반영해야 한다. 각 필드의 데이터 타입(string, integer, boolean, array 등)과 형식(date-time, email, uuid 등)을 구체적으로 명시하고, 가능한 값의 범위를 enum으로 제한하거나 minimum, maximum, pattern(정규식)으로 제약을 걸어 명세의 정확도를 높인다. 또한, 필드에 대한 설명(description)을 상세히 기입하여 API 사용자의 이해를 돕는 것이 중요하다.

API 명세서에는 인증 및 권한 부여 방식을 명시적으로 정의해야 한다. 일반적인 방식으로는 API 키, OAuth, JWT 등을 사용하며, 각 엔드포인트별로 필요한 권한 수준(예: 읽기 전용, 쓰기 권한, 관리자 권한)을 기술한다. 인증이 필요한 요청과 그렇지 않은 요청을 구분하여 문서화하는 것이 중요하다.

에러 처리는 API의 견고성을 보여주는 핵심 요소이다. 명세서에는 발생 가능한 모든 HTTP 상태 코드와 그에 상응하는 에러 응답 형식을 정의해야 한다. 일반적인 4xx 및 5xx 에러 외에도, 비즈니스 로직상 발생할 수 있는 커스텀 에러 코드와 메시지, 해결 방안에 대한 힌트를 포함하는 것이 좋다. 일관된 에러 응답 구조(예: code, message, details 필드)를 설계하여 클라이언트 개발자가 쉽게 처리할 수 있도록 한다.

예제는 API 명세서의 가독성과 실용성을 극대화한다. 각 주요 엔드포인트에 대해 실제 요청과 성공적인 응답, 그리고 실패 시의 응답 예제를 포함해야 한다. 예제는 가능한 실제 운영 환경과 유사한 데이터를 사용하여 작성하며, 복잡한 요청 본문이나 쿼리 파라미터 사용법을 명확히 보여주는 데 중점을 둔다. Swagger 등의 도구는 이러한 예제를 시각적으로 보여주고, 사용자가 브라우저에서 직접 테스트해볼 수 있는 인터페이스를 제공한다.

Swagger와 OpenAPI가 널리 사용되지만, API 설계와 문서화를 위한 다른 유명한 도구와 명세 언어도 존재한다. 각 도구는 고유한 철학, 문법, 장점을 가지고 있어 프로젝트의 요구사항과 팀의 선호도에 따라 선택할 수 있다.

Postman은 초기에는 API 테스트 도구로 시작했으나, 포괄적인 API 개발 플랫폼으로 진화했다. Postman은 사용자 친화적인 그래픽 인터페이스를 제공하여 API 요청을 구성하고 테스트하며, 수집된 요청들을 '컬렉션'으로 관리할 수 있다. 최근에는 Postman에서 직접 API 명세를 설계하고([5]), 생성된 명세를 기반으로 문서를 자동 생성하고, 모의 서버를 운영하며, 자동화된 테스트를 수행하는 등 API의 전체 라이프사이클을 관리하는 기능을 강화하고 있다.

다음은 주요 대안 명세 언어와 도구를 비교한 표이다.

API Blueprint는 Markdown 문법을 기반으로 하여 작성자가 쉽게 읽고 쓸 수 있는 것을 최우선으로 설계되었다. 이는 개발자와 비개발자 모두가 API 설계에 참여하기 용이하게 만든다. Apiary는 API Blueprint를 위한 호스팅 플�랫폼으로, 명세서 작성, 대화형 문서 자동 생성, 모의 서버 제공, 협업 기능을 한데 모아 제공한다.

RAML은 YAML을 사용하여 API를 모델링하는 데 중점을 둔다. 리소스, 메서드, 매개변수, 응답 등을 재사용 가능한 단위로 정의할 수 있는 트레잇(Trait)과 리소스 타입(ResourceType) 같은 기능을 제공하여 대규모이고 일관된 API 설계를 효율적으로 관리하는 데 유리하다.

Redoc과 Stoplight는 OpenAPI Specification 기반의 API 문서를 시각적으로 풍부하게 표현하는 데 특화된 도구이다. 이들은 기본적인 Swagger UI보다 향상된 사용자 경험과 디자인 커스터마이징 옵션을 제공한다.

Redoc은 OpenAPI 명세 파일을 입력받아 단일 정적 HTML 파일로 반응형 문서를 생성한다. 삼단 레이아웃을 채용하여 탐색, 콘텐츠, 샘플 응답을 명확하게 구분한다. 주요 특징은 설치와 사용이 간단하며, 테마와 플러그인을 통해 디자인을 확장할 수 있다는 점이다. 특히 코드 샘플의 가독성이 뛰어나고, 여러 언어의 SDK 생성 옵션을 내장하고 있다는 장점이 있다.

Stoplight는 단순한 문서 시각화를 넘어서 API 설계, 문서화, 테스트, 모의 서버 제공을 아우르는 통합 플랫폼이다. 그래픽 기반의 편집기를 통해 시각적으로 API를 설계할 수 있으며, 변경 사항이 실시간으로 명세 파일에 반영된다. 협업 기능에 중점을 두어 팀원 간의 리뷰, 스타일 가이드 검증, 버전 관리가 용이하다. 문서화 측면에서는 사용자가 테마를 자유롭게 커스터마이징할 수 있고, 문서 사이트를 별도로 호스팅할 수 있다.

이들 도구는 프로젝트의 요구사항에 따라 선택된다. 빠르고 가벼운 문서 생성이 목표라면 Redoc이 적합하고, API의 전 주기(설계부터 문서 게시까지)를 하나의 플랫폼에서 관리하고 강력한 협업이 필요하다면 Stoplight와 같은 통합 솔루션이 유용하다.