웹 서비스 개발 – API 개발 기초 – 3 – JSON과 XML 데이터 처리

작성자 wooah
웹 서비스 개발 - API 개발 기초 - 3 - JSON과 XML 데이터 처리
웹 서비스 개발 – API 개발 기초 – 3 – JSON과 XML 데이터 처리

웹 서비스 개발 – API 개발 기초 – API 문서 작성 (Swagger, OpenAPI 등)

안녕하세요! 😊
이번 시간에는 백엔드 개발의 마지막 퍼즐조각이자,
팀 협업과 외부 연동에 있어서 매우 중요한 요소인 API 문서 작성에 대해 이야기해보겠습니다.

“API 문서가 없으면, 아무리 멋진 API도 쓸 수 없다!”
이 말처럼, API 문서는 개발자 간의 소통의 다리이자 설명서 역할을 해요.

특히 요즘에는 Swagger나 OpenAPI 같은 도구들을 이용해 자동화된 문서 생성도 가능하답니다.
그럼 지금부터 차근차근 알아볼까요?

1. API 문서란?

API 문서란, 서버가 제공하는 API의 요청 형식, 응답 형식, 파라미터, 에러 코드, 인증 방법 등을 체계적으로 정리한 문서입니다.

마치 이런 설명서 같아요 📚

  • 어떤 URL로 요청해야 하는지?
  • 어떤 방식(POST/GET/PUT 등)으로 요청해야 하는지?
  • 어떤 데이터를 넣어야 하는지?
  • 어떤 응답이 오는지?
  • 에러가 나면 어떤 코드가 나오는지?

2. API 문서가 중요한 이유

이유 설명
📌 협업 용이 프론트엔드, 모바일 개발자와의 연동에 필수
🧪 테스트 편의 요청/응답 예시가 있어 테스트가 쉬움
🔒 보안 강화 인증 방식 명확화로 보안 설계에 도움
📦 유지보수 용이 API 변화 추적 및 관리가 쉬워짐
🌍 외부 공개 가능 외부 개발자 대상의 API 제공 시 꼭 필요

3. OpenAPI & Swagger란?

✅ OpenAPI란?

  • 이전 이름은 Swagger 사양이었고, 현재는 **OpenAPI Specification(OAS)**로 불려요.
  • RESTful API의 명세를 JSON이나 YAML로 작성해서 표준화된 문서를 만드는 형식입니다.

✅ Swagger란?

  • OpenAPI 문서를 시각화하고, 테스트할 수 있는 도구입니다.

  • 대표적으로:

    • Swagger UI: 웹에서 문서를 보기 쉽게 렌더링
    • Swagger Editor: 명세 작성용 에디터
    • Swagger Codegen: 명세 기반 코드 자동 생성 도구

4. 문서에 포함되어야 할 필수 항목

항목 설명
엔드포인트 URL /users, /products/{id}
메서드(Method) GET, POST, PUT, DELETE 등
요청 파라미터 쿼리, 경로, 헤더, 바디
요청/응답 예시 JSON 데이터 구조
상태코드 설명 200, 201, 400, 404, 500 등
인증 방식 JWT, OAuth2, API 키 등

5. Swagger(OpenAPI) 예제 (YAML 기반)

openapi: 3.0.0
info:
  title: 사용자 API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 사용자 목록 조회
      responses:
        '200':
          description: 성공
          xss-content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /users/{id}:
    get:
      summary: 특정 사용자 조회
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 성공
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

이 문서를 Swagger UI에 연결하면 자동으로 보기 좋게 시각화된 문서가 생성돼요!

6. Swagger UI 사용하기

방법 1: Swagger 공식 사이트에서 사용

방법 2: 로컬 프로젝트에 설치

Node.js 기반 API 프로젝트라면:

npm install swagger-ui-express
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.yaml');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

PHP 기반 프로젝트에서도 Laravel이나 Lumen, Slim 등은 Swagger와 연동이 가능합니다!

7. Postman으로 API 문서화하기 (보조 수단)

Postman을 사용하면 요청/응답을 테스트하고, API 설명서도 자동 생성할 수 있어요.

  • 요청을 모아 “컬렉션”으로 관리
  • 자동 문서화
  • Swagger 문서로 내보내기 또는 가져오기 가능

Swagger는 사양 중심, Postman은 테스트 중심 도구로 보면 좋아요!

8. 문서 작성 시 주의사항 ✅

체크포인트 설명
최신화 유지 API가 바뀌면 문서도 즉시 반영하기
요청 예시 실제 사용할 수 있는 JSON 예제 제공
응답 구조 전체 구조를 표기 (중첩된 객체 포함)
필수/선택 구분 required 여부를 반드시 명시
상태코드 설명 어떤 상황에서 어떤 코드가 반환되는지 명확히 작성

9. 문서 자동 생성 프레임워크

언어/프레임워크 문서 자동 생성 도구
Laravel (PHP) l5-swagger, scribe
Node.js (Express) swagger-jsdoc, swagger-ui-express
Spring Boot (Java) SpringDoc, Swagger2
Python (Flask) Flasgger, apispec
NestJS 내장 Swagger 모듈

마무리하며 😊

잘 만든 API도, 문서 없이는 무용지물입니다.
특히 팀 개발, 프론트-백 연동, 외부 API 제공 등 다양한 상황에서
API 문서는 명확한 커뮤니케이션 도구이자, 품질의 기준선이 되죠!

Swagger와 OpenAPI를 이용해 자동화된 문서 시스템을 구축해보세요.
한 번 잘 세팅해두면, 나중에 유지보수도 훨씬 편해지고
협업 개발자에게도 신뢰받는 개발자가 될 수 있어요! 😄

다음 편에서는 **API 인증 방식(JWT, OAuth 등)**에 대해 다룰게요!
오늘도 깔끔한 개발 문화를 위해 화이팅입니다! 🚀💪📘

답글 남기기