스웨거를 사용하여 Node.js API 만들기

API 문서는 소프트웨어 개발의 중요한 구성 요소로, 사용자에게 API 및 그 서비스와 상호 작용하는 방법에 대한 통찰력을 제공합니다. 이 가이드에서는 자동 생성 가능한 대화형 API 문서를 문서화하고 API 테스트를 용이하게 하기 위해 Node.js로 구축된 API를 문서화하는 도구인 Swagger를 활용하는 방법을 탐구합니다.

추가적으로, 다양한 프로토콜에 걸쳐 테스트와 원활한 협업을 포함하는 강력한 API 관리를 위한 통합 도구로 Apidog를 소개합니다. 단계별 안내와 통찰력을 통해 개발자는 API 개발을 간소화하고 애플리케이션의 견고성과 효율성을 보장할 수 있습니다.

button

Swagger에서 API 문서화에 대한 궁극적인 가이드

Swagger를 사용하여 개발자는 간단하고 직관적인 YAML 또는 JSON 형식을 사용하여 API 엔드포인트, 요청 매개변수, 응답 형식 및 인증 방법을 정의할 수 있습니다. 이 표준화된 문서 형식은 개발 팀 간의 소통을 촉진할 뿐만 아니라 클라이언트의 API 소비를 간소화합니다.

Node.js 환경 설정하기

Swagger로 Node.js API를 생성하기 전에 개발 환경이 제대로 설정되었는지 확인합시다. 머신에 Node.js가 설치되어 있는지 확인하세요. 공식 웹사이트에서 Node.js를 다운로드하고 설치하거나 npm 또는 yarn과 같은 패키지 관리자를 사용할 수 있습니다.

Swagger 도구 설치하기

Swagger를 시작하기 위해 필요한 Swagger 도구를 설치해야 합니다. Swagger 생태계는 API 개발의 다양한 단계에 사용할 수 있는 다양한 도구를 제공합니다:

Swagger Editor: Swagger 사양을 설계하고 테스트하는 웹 기반 편집기입니다.
Swagger UI: Swagger 문서를 시각화하고 상호작용하는 사용자 친화적인 인터페이스입니다.
Swagger Codegen: Swagger 사양을 기반으로 서버 스텁 및 클라이언트 라이브러리를 생성하는 도구입니다.

npm 또는 yarn을 사용하여 이러한 도구를 전역적으로 설치할 수 있습니다:

npm install -g swagger-cli swagger-ui-express

Swagger로 API 설계하기

개발 환경이 설정되고 Swagger 도구가 설치되었으므로, 이제 Swagger를 사용하여 Node.js API 설계를 시작할 수 있습니다. 첫 번째 단계는 우리의 API 엔드포인트, 요청 매개변수, 응답 스키마 및 기타 관련 세부정보를 설명하는 Swagger 사양 파일(일반적으로 YAML 또는 JSON 형식)을 만드는 것입니다.

다음은 간단한 Todo API에 대한 Swagger 사양의 기본 예입니다:

openapi: 3.0.0
info:
  title: Todo API
  version: 1.0.0
  description: 간단한 Todo API
paths:
  /todos:
    get:
      summary: 모든 todo 가져오기
      responses:
        '200':
          description: todo 목록
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    title:
                      type: string
                    completed:
                      type: boolean
    post:
      summary: 새로운 todo 만들기
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example: 장보기
                completed:
                  type: boolean
                  example: false
      responses:
        '201':
          description: 생성됨

이 Swagger 사양에서:

우리는 info 섹션에서 API 제목, 버전 및 설명을 정의합니다.
우리는 모든 todo를 가져오는 (GET) 하나와 새로운 todo를 만드는 (POST) 두 개의 엔드포인트(/todos)를 지정합니다.
각 엔드포인트는 요약, 요청 본문(해당되는 경우) 및 응답 스키마를 포함합니다.

Swagger에서 API 테스트하기

API 문서 작성을 완료하면 Swagger 문서를 보고 이를 사용하여 API를 테스트할 수 있어야 합니다. 이전에 설명한 단계를 따랐다면 아래 설명된 것과 유사한 인터페이스를 보아야 합니다. 우리의 문서는 /docs 경로에서 제공됩니다.

우리는 Swagger 문서 UI를 사용하여 몇 가지 요청을 하고 결과를 관찰할 것입니다.

사용자 생성:

게시물 생성:

위의 예에서 알 수 있듯이, 우리는 Swagger 문서를 사용하여 API를 테스트할 수 있으며, 이를 통해 데이터베이스에서 데이터를 생성, 읽기 및 수정할 수 있습니다. 이는 API를 이해하고 통합하는 데 도움을 줍니다.

이러한 예를 따라 PUT을 사용하여 사용자나 게시물을 업데이트하거나, GET을 사용하여 사용자나 게시물을 읽고, DELETE를 사용하여 데이터베이스에서 삭제하는 등의 다른 요청 방법을 계속 테스트할 수 있습니다.

결론적으로, API 문서는 소프트웨어 개발 수명 주기에 중요한 역할을 하며, 협업을 촉진하고 원활한 사용자 경험을 보장합니다. Swagger의 이점 중 일부는 다음과 같습니다:

서버와 클라이언트 간의 API 문서 동기화.
REST API 문서 생성 및 상호작용 촉진. Swagger UI 프레임워크를 활용하면 매개변수에 대한 API 응답에 대한 포괄적인 통찰력을 제공합니다.
JSON 및 XML 형식으로 응답 제공.
다양한 기술에 걸쳐 구현할 수 있는 다양성.

Apidog로 API 문서 관리하기

Swagger로 API를 관리하는 것은 때때로 번거롭고 팀 간 협력이 부족할 수 있으므로 Apidog를 대신 사용하는 것을 제안합니다.

Apidog는 Postman에 비해 더 강력한 API 테스트 도구입니다. HTTP(s), WebSocket, Socket, gRPC와 같은 프로토콜에 대한 디버깅 인터페이스를 지원하며, IDEA 플러그인과 통합됩니다.

button

API를 개발한 후, Apidog의 IDEA 플러그인을 사용하여 여러 플랫폼에서 API 문서를 쉽게 생성할 수 있어 테스트 및 유지 관리가 매우 편리합니다.

Swagger를 JSON으로 내보내기

아래 그림과 같이 "변환 및 JSON으로 저장"을 선택하여 Swagger 문서를 JSON 파일로 내보냅니다.

Apidog에 Swagger 파일 가져오기

Apidog를 열고 프로젝트를 만든 후 "프로젝트 설정->데이터 가져오기->OpenAPI/Swagger->파일 가져오기"로 이동하여 이전에 내보낸 Swagger 형식의 JSON 파일을 가져옵니다.

가져오는 동안 미리보기가 제공되며, 모든 것을 가져오거나 API를 선택적으로 가져올 수 있습니다. 가져오기가 성공하면 API를 테스트할 환경을 선택할 수 있습니다.

자세한 내용은 이 링크를 확인하세요: https://apidog.com/help/importing-and-exporting-data/importing-data/importing-openapi-specification