API(5) - 오픈 API 명세와 Swagger

안녕하세요. 오늘은 아침부터 글을 작성하니 새롭네요.

저번 시간에는 gRPC에 대해서 학습했습니다. 이번 시간에는 오픈 API 명세와 Swagger에 대해 알아보겠습니다.

---

API 명세

API 명세란 클라이언트와 서버가 어떤 방식으로 통신해야 하는지를 정리한 문서입니다.

어떤 URL로 요청을 보내야 하는지, 어떤 데이터를 전달해야하는지, 어떤 응답이 반환되는지를 명확하게 설명하는 역할을 합니다.

 

API 명세가 필요한 이유

API 명세가 없으면 프론트엔드와 백엔드가 요청 형식과 응답 구조를 다르게 이해할 수 있습니다. 따라서 API 명세는 협업 과정에서 혼란을 줄이고, 개발과 테스트를 더 효율적으로 진행할 수 있도록 도와줍니다.

 

OAS(OpenAPI Specification)

OAS(OpenAPI Specification)는 REST API를 일정한 형식으로 설명하기 위한 표준 명세입니다.

즉, API의 엔드포인트, 요청 방식, 파라미터, 요청 본문, 응답 구조, 인증 방식 등을 사람이 읽고 도구가 해석할 수 있는 형태로 정리하는 규칙이라고 볼 수 있습니다.

 

예를 들어 어떤 API가 있다면 OAS를 통해 다름과 같은 내용을 명확하게 표현할 수 있습니다.

• 어떤 URL로 요청을 보내야 하는지
• 어떤 HTTP 메서드를 사용하는지
• 어떤 파라미터를 전달해야 하는지
• 요청 본문은 어떤 형식인지
• 응답은 어떤 데이터 구조로 반환되는지
• 인증은 어떤 방식으로 해야 하는지

즉, OAS는 단순한 설명 문서가 아닌 API를 구조적으로 표현하기 위한 표준 규칙입니다.

 

OAS의 예시

보통 YAML 또는 JSON 형식으로 작성하며, YAML이 더 읽기 편해서 많이 사용됩니다.

openapi: 3.0.0 # openAPI 3.0 버전 명시
info: # API 버전 및 설명
  version: 1.0.0
  title: User API
  description: A sample API to illustrate OpenAPI concepts
  
servers: #목록으로 여러개의 url 사용 가능
- url: https://example.com/exam # API 엔드포인트 경로 정의

paths:
  /users/{id}:
    get: 
      summary: 사용자 조회
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses: #responses 필수
        '200': 
          description: 조회 성공

해당 명세는 /users/{id} 경로에 대해 GET 요청을 보낼 수 있고, id라는 path parameter가 필요하며, 성공 시 200 응답을 반환한다는 의미를 담고 있습니다.

 

즉, OAS는 API를 사람이 읽을 수 있도록 정리하는 동시에 도구가 해석할 수 있도록 구조화된 형식으로 작성됩니다.

 

Swagger

Swagger는 OAS 자체를 의미하는 것이 아닌 OAS를 기반으로 API 문서를 시각적으로 보여주고 활용할 수 있게 해주는 도구 모음입니다.

즉, OAS는 API를 설명하는 표준명세이고 Swagger는 그 명세를 보기 쉽게 보여주고 테스트하기 쉽게 해주는 도구라고 이해하면 됩니다.

 

Swagger를 사용하면 API 문서를 단순한 텍스트 파일로만 보는 것이 아닌 웹 화면에서 엔드포인트 목록을 확인하고, 요청 파라미터를 입력해 직접 테스트할 수 있습니다.

 

장점

• API 구조를 쉽게 파악할 수 있다.
• 프론트엔드와 백엔드 협업에 유리하다.
• 테스트와 검증이 편리하다.
• 문서화 효율이 높아진다.

단점

• 자동 생성만으로는 설명이 부족할 수 있다.
• 운영 환경에 그대로 노출하면 보안상 주의가 필요하다.
• 실제 API 설계가 좋지 않으면 문서도 좋은 문서가 되지 않는다.

---

여기까지 오픈 API 명세와 Swagger에 대해서 학습해보았습니다. Swagger같은 경우는 간단하게 설명만 하고 끝냈는데, 추후에 직접 연동하는 방법으로 가져오면 좋을 것 같아서 일부러 나눴습니다.

이제 정말 얼마 안남은 것 같네요. 대략 절반정도 더 하면 백엔드 로드맵에 해당되는 내용은 끝나게 될 것 같습니다. 아마 그러면 여태 다루지 못한 세부적인 내용이나 실제 연동, 트러블슈팅에 대해 다룰 것 같습니다.

다음 시간에는 CDN, Redis 등 캐시에 대한 얘기로 가져오겠습니다. 수고하셨습니다.