Swagger 는 개발자가 RESTful API를 신속하게 설계, 구축 및 테스트할 수 있도록 돕는 인기 있는 API 개발 도구입니다. Swagger 공식 웹사이트는 많은 도구와 라이브러리를 제공하며, 그 중 Swagger Editor는 개발자가 Swagger 사양 파일을 작성하고 편집하는 데 특히 유용한 도구입니다. 이 기사에서는 Swagger Editor의 기본 사항과 사용법을 소개합니다.
Swagger Editor 사용의 장점
Swagger Editor는 OpenAPI 사양을 작성하고 테스트하기 위한 오픈 소스 도구로, 다음과 같은 장점이 있습니다:
- OpenAPI 사양 작성 및 테스트: Swagger Editor는 개발자가 시각적인 편집기에서 OpenAPI 사양을 작성하고, 이러한 사양의 기능 및 응답을 동일한 인터페이스에서 즉시 테스트할 수 있도록 합니다.
- 자동 완성과 오류 검사: Swagger Editor는 개발자가 OpenAPI 사양을 작성할 때 키워드와 매개 변수를 자동으로 완성하도록 도와주며, 일반적인 구문 오류 및 사양 오류를 피하기 위해 실시간 오류 검사를 제공합니다.
- 쉽고 간편한 협업: Swagger Editor는 여러 개발자가 동일한 OpenAPI 사양에 협력할 수 있게 하여, 개발 팀 내에서 API 사양을 공유하고 논의하기 쉽게 만듭니다.
- 다른 Swagger 도구와의 통합: Swagger Editor는 Swagger UI 및 Swagger Codegen과 같은 다른 Swagger 도구와 통합되어, 개발자에게 포괄적인 API 개발 및 테스트 솔루션을 제공합니다.
Swagger Editor 시작하기
Swagger Editor 설치하기
Swagger Editor는 두 가지 방법으로 설치 및 실행할 수 있습니다:
- 온라인 사용: Swagger는 자사 웹사이트에서 Swagger Editor의 온라인 버전을 제공하며, 사이트 방문만으로도 간단하게 사용할 수 있습니다. 이 방법은 설치가 필요 없으며 직접 사용할 수 있습니다.
- 로컬 설치: Swagger는 또한 자사 웹사이트에서 Swagger Editor의 로컬 버전을 제공하며, GitHub에서 다운로드할 수 있습니다. 다운로드 후, 파일을 추출하고 다음 명령어를 실행하여 시작합니다:
npm install
npm start
Swagger Editor UI 이해하기
Swagger Editor는 RESTful API를 설계, 구축 및 테스트하기 위해 인기 있는 도구입니다. 개발자가 OpenAPI 사양을 작성하고 테스트할 수 있는 사용자 친화적인 UI를 제공하며, 자동 완성 및 오류 검사와 같은 기능을 포함하고 있습니다.
편집 영역은 사양을 작성하고 편집하기 위한 중앙 위치이며, 사이드 패널은 사양의 다양한 부분 간에 쉽게 탐색할 수 있도록 합니다. Info 탭은 API에 대한 일반 정보를 표시하고, Paths 탭은 엔드포인트 목록을 제공합니다. Definitions 탭은 개발자가 데이터 모델을 생성하거나 편집할 수 있도록 하고, Parameters 탭은 매개 변수 목록을 제공합니다. Responses 탭은 응답 목록을 표시하며, Security 탭은 API에 대한 인증 및 권한 부여 메커니즘을 지정합니다.
Swagger Editor 사용 방법
Swagger Editor를 시작한 후, 다음 기본 작업을 통해 Swagger 사양 파일을 생성하고 편집할 수 있습니다:
새 Swagger 사양 파일 생성하기
Swagger Editor를 시작하면 빈 Swagger 사양 파일이 자동으로 열립니다. 새 Swagger 사양 파일을 생성하려면 왼쪽의 "새 문서" 버튼을 클릭합니다.
Swagger 사양 파일 편집하기
Swagger Editor에서 Swagger 사양 파일을 쉽게 편집할 수 있습니다. 왼쪽 패널에는 Swagger 사양 파일의 트리 구조가 표시되고, 오른쪽 패널에는 해당 YAML 형식 코드가 표시됩니다. 왼쪽 패널의 트리 구조에서 아무 노드를 더블 클릭하면 해당 YAML 코드를 편집할 수 있습니다. 편집한 후, 왼쪽 상단 모서리에 있는 "검증" 버튼을 클릭하여 코드가 Swagger 사양을 준수하는지 확인할 수 있습니다.
Swagger 문서 미리보기
Swagger Editor에서 Swagger 문서를 쉽게 미리 볼 수 있습니다. 왼쪽의 "미리 보기" 버튼을 클릭하면 오른쪽 브라우저 창에서 Swagger 문서의 미리보기 효과를 확인할 수 있습니다. Swagger API 인터페이스를 테스트하고 미리보기 창에서 반환된 결과를 볼 수 있습니다.
Swagger 사양 파일 가져오기 및 내보내기
Swagger Editor에서 Swagger 사양 파일을 쉽게 가져오고 내보낼 수 있습니다. 왼쪽 상단 모서리의 "파일" 버튼을 클릭하고 "URL 가져오기" 또는 "파일 가져오기"를 선택하여 Swagger 사양 파일을 가져올 수 있습니다. 또한 "다른 이름으로 다운로드"를 선택하여 Swagger 사양 파일을 내보낼 수 있습니다.
기타 기능
위에서 설명한 기본 작업 및 방법 외에도 Swagger Editor는 다음과 같은 많은 기능을 제공합니다:
- 자동 완성과 구문 강조;
- Swagger 2.0 및 OpenAPI 3.0 사양 지원;
- 사용자 지정 가능한 스타일 및 레이아웃;
- 여러 형식의 데이터 입력 및 출력 지원.
OpenAPI 사양에 대하여
OpenAPI 사양 (Swagger 사양으로도 알려져 있음)은 RESTful API를 설명하기 위한 표준입니다. API 인터페이스 정보, 요청 매개 변수 및 응답 값과 같은 메타데이터를 정의하고, 자동화 도구를 지원합니다. OpenAPI 사양은 처음에 Swagger에 의해 제안되었으며, 현재는 여러 기업과 조직의 지원을 받는 개방형 표준이 되었습니다.
OpenAPI 사양은 개발자와 팀이 RESTful API를 보다 효과적으로 설계, 작성 및 테스트하도록 도와주며, 가독성과 유지 관리성을 향상시킵니다. OpenAPI 사양의 주요 특징은 다음과 같습니다:
- 설명 언어: OpenAPI 사양은 YAML 또는 JSON과 같은 설명 언어를 사용하여 API 인터페이스 정보를 설명합니다. API 경로, 매개 변수, 요청 본문, 응답 및 오류 코드를 정의할 수 있습니다.
- 시각적 문서: OpenAPI 사양은 온라인 테스트 및 디버깅을 지원하는 시각적 API 문서를 생성할 수 있습니다.
- 확장성: OpenAPI 사양은 다양한 비즈니스 요구에 맞추기 위해 사용자 지정 속성과 확장을 지원합니다.
- 크로스 언어 지원: OpenAPI 사양은 Java, Node.js, Python 및 Go와 같은 다양한 언어의 코드 생성 도구에서 지원될 수 있습니다.
OpenAPI 사양은 RESTful API를 설명하는 통합 표준을 제공하여, 서로 다른 팀이 API를 보다 쉽게 소통하고 공유할 수 있도록 합니다. 동시에 API 개발자가 API를 설계하고 작성하며 테스트할 수 있는 편리한 도구와 프레임워크를 제공합니다.
코드로 Swagger 작성하기
개발자가 코드로 Swagger를 작성할 수 있다면, 특히 VSCode에서 더욱 효과적일 수 있습니다. 여러 이유로 인해 다음과 같은 이유가 있습니다:
- 시간 절약 및 효율성: 코드에서 Swagger를 생성하면 Swagger를 수동으로 작성해야 하는 작업량을 크게 줄일 수 있으며, 특히 대규모 프로젝트의 경우 수동으로 완료하는 데 며칠 또는 몇 주가 걸릴 수 있지만 자동화 도구를 통해 몇 분 내에 생성될 수 있습니다.
- 더욱 정확한 문서: 코드에서 Swagger를 생성하면 Swagger 문서와 실제 코드 간의 일관성을 보장하여, 문서와 코드가 일치하지 않는 상황을 피하고 API 문서를 더욱 정확하게 만듭니다.
- 더 나은 유지 관리성: 코드에서 Swagger를 생성하면 Swagger 문서와 코드가 일치하기 때문에 API 유지 관리가 쉬워집니다. API 변경이 발생하면 코드만 업데이트하면 되고, Swagger 문서는 자동으로 업데이트되어 유지 관리 작업의 난이도를 줄입니다.
- 더 나은 재사용성: 코드에서 Swagger를 생성하면 생성된 Swagger 문서를 다른 개발자, 테스터 또는 API 클라이언트가 재사용할 수 있는 더 많은 정보를 포함하므로 중복 작업에 소요되는 시간과 노력을 줄입니다.
Swagger Editor보다 나은 선택
Design First 팀의 경우, Apidog 는 매우 추천되는 보다 진보된 API 디자인 도구입니다. JSON 구조에 익숙하기만 하면 Apidog에서 API를 설계하는 비결을 익힐 수 있습니다. Apidog는 Postman, Swagger, Mock 및 JMeter를 결합한 것입니다.
Apidog에서는 OpenAPI 사양을 준수하는 API를 설계할 수 있을 뿐만 아니라, API 디버깅, 테스트 및 문서 공유와 같은 일련의 과정을 완료할 수 있습니다. Apidog는 포괄적인 API 관리 솔루션을 제공합니다. Apidog를 사용하면 통합된 플랫폼에서 API를 설계하고, 디버깅하고, 테스트하며 협업할 수 있어 서로 다른 도구 간 전환 및 데이터 불일치 문제를 제거할 수 있습니다. Apidog는 API 작업 흐름을 간소화하고 프론트 엔드, 백 엔드 및 테스트 인력 간의 효율적인 협업을 보장합니다.
