LEVEL 75 QUEST

API 문서 자동 생성 - Swagger/OpenAPI

API 문서 자동 생성 - Swagger/OpenAPI — DevFoil 바이브코딩 Stage 16, Lv.75

API 문서, 왜 자동화해야 하는가?

문서 없는 API는 지도 없는 도시

아무리 잘 만든 API도 문서가 없으면 아무도 사용하지 못합니다. 하지만 문서를 수동으로 관리하면 코드와 문서가 어긋나는 문제가 발생합니다.

OpenAPI(Swagger) 표준을 사용하면 코드에서 문서를 자동 생성하고, 인터랙티브 문서 UI에서 바로 API를 테스트할 수도 있습니다.

이 강의에서 다루는 내용:

OpenAPI 스펙(OAS) 3.0 기본 구조
Swagger UI로 인터랙티브 문서 자동 생성
코드에서 문서 자동 추출
API 문서 기반 테스트 자동화

OpenAPI 스펙 기본 구조

YAML로 API를 정의하다

OpenAPI 스펙은 API의 모든 것을 기술하는 표준 문서입니다. 엔드포인트, 요청/응답 형식, 인증 방식, 에러 코드까지 정의합니다.

# AI 프롬프트: "사용자 API의 OpenAPI 3.0 스펙을 작성해줘"
openapi: 3.0.3
info:
  title: 사용자 관리 API
  description: 사용자 CRUD 및 인증 API
  version: 1.0.0
  contact:
    name: API 지원팀
    email: api-support@myapp.com

servers:
  - url: https://api.myapp.com/v1
    description: 프로덕션 서버
  - url: http://localhost:3000/v1
    description: 개발 서버

paths:
  /users:
    get:
      summary: 사용자 목록 조회
      tags: [사용자]
      parameters:
        - name: page
          in: query
          schema: { type: integer, default: 1 }
        - name: limit
          in: query
          schema: { type: integer, default: 20, maximum: 100 }
        - name: status
          in: query
          schema: { type: string, enum: [active, inactive] }
      responses:
        '200':
          description: 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      users:
                        type: array
                        items: { $ref: '#/components/schemas/User' }
                      pagination: { $ref: '#/components/schemas/Pagination' }

    post:
      summary: 사용자 생성
      tags: [사용자]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateUser' }
      responses:
        '201':
          description: 생성 완료
        '400':
          description: 유효성 검사 실패
        '409':
          description: 이메일 중복

components:
  schemas:
    User:
      type: object
      properties:
        id: { type: string }
        email: { type: string, format: email }
        name: { type: string }
        role: { type: string, enum: [user, editor, admin] }
        createdAt: { type: string, format: date-time }

    CreateUser:
      type: object
      required: [email, password, name]
      properties:
        email: { type: string, format: email }
        password: { type: string, minLength: 8 }
        name: { type: string }

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

🔒

여기까지는 미리보기입니다

API 문서 자동 생성 - Swagger/OpenAPI
무료 가입하면 이어서 볼 수 있고, 강의를 완료할 때마다 XP와 레벨이 쌓입니다.

Google로 3초 만에 시작 →🧵 Threads로 시작 무료 공개 강의 둘러보기 (Lv.1~3)