Swagger는 RESTful API를 설계, 문서화 및 사용하는 데 도움을 주는 오픈 소스 소프트웨어 프레임워크입니다. 개발자는 OpenAPI 사양(이전에는 Swagger 사양이라 불렸음)을 사용하여 기계가 읽을 수 있는 형식으로 API를 설명할 수 있습니다. OpenAPI 사양은 RESTful API를 설명하는 표준으로서 다양한 도구와 플랫폼 간의 상호 운용성을 제공합니다.
Swagger를 사용하면 개발자는 API의 엔드포인트, 매개변수, 응답 및 기타 세부 정보를 설명하는 Swagger 파일을 작성할 수 있습니다. 이 파일은 자동으로 문서화를 생성하는 데 사용될 수 있으며, 이를 통해 개발자 및 사용자가 API를 사용하는 방법을 이해할 수 있습니다. 또한 Swagger를 사용하여 다양한 프로그래밍 언어에서 클라이언트 라이브러리를 생성할 수 있으며, 이를 통해 개발자가 API를 사용하기 쉬워집니다.
전반적으로 Swagger는 API 개발을 단순화하고 보다 넓은 대중에게 접근 가능하게 만들어, API를 설명하고 문서화하는 표준화된 방법을 제공합니다.
예시로, 다음은 Swagger로 작성된 간단한 API 설명서입니다.
openapi: 3.0.0
info:
title: My API
description: This is a simple API
version: 1.0.0
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: Get a list of users
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
type: object
properties:
name:
type: string
age:
type: integer
위 예시는 "My API"라는 제목을 가진 버전 1.0.0의 간단한 API입니다. 이 API에서는 /users 경로에서 GET 요청을 수행하면 사용자 목록을 반환합니다. 반환되는 데이터는 JSON 배열로, 사용자의 이름과 나이 정보를 포함합니다. 이러한 정보를 기반으로 자동으로 문서화가 생성될 수 있습니다.
어떤 완성된 웹사이트로 API를 제공하면 좋겠지만, API 문서를 가독성 있게 만드는 것 자체가 큰 일입니다. 따라서 API 문서에 필요한 각종 항목의 내용을 정해진 규칙에 맞게 JSON이나 YAML 문서로 작성해놓으면, 멋진 API 문서가 만들어지도록 만든 서비스가 존재합니다.
바로 Swagger라는 서비스입니다. 특히 그 중에서도 Swagger Editor를 사용하면 YAML을 API 문서로 변환해줍니다.
https://swagger.io/tools/swagger-editor/
YAML은 데이터 포맷이면서, 동시에 마크업 언어입니다. 해당 문법에 대해서는 별도로 다룹니다. 문법을 몰라도 작성할 수 있을 만큼 쉽습니다.
당연히 코드로 작성하는 YAML 파일에는 규칙이 존재합니다. 규칙대로 써야만 API 문서가 만들어지니까요. 이 규칙을 OpenAPI 명세라고 부릅니다. 현재는 3.0.x 버전을 주로 사용하고 있습니다.
API 문서 살펴보기
왼쪽이 YAML 파일, 오른쪽이 결과물입니다. 결과물에는 엔드포인트와 메소드 및 Path, 그리고 Path를 누르면, 어떤 응답이 오는지까지 시각적으로 잘 표현되어 있습니다.
다음의 예제는 반려동물의 ID를 통해 반려동물의 정보를 조회하는 엔드포인트입니다.
다음 기능에 대한 REST API 모범 사례를 연구해서 제출하세요.
특정 블로그 글에 달린 댓글 조회 REST API 모범 사례
블로그 글 좋아요 블로그 글 좋아요 취소의 REST API 모범 사례
다른 글쓴이 팔로우 REST API 모법 사례