Swagger 사용법, API 문서와 호출 방법

안녕하세요. 사랑받는 IT 프로덕트의 첫걸음, 똑똑한개발자입니다.

오늘의 인사이트 요약

1. swagger란 OpenAPI 명세를 다루는 도구 묶음의 이름이며 명세 형식은 지금 OpenAPI라고 부릅니다.

2. Swagger 사용법은 코드에서 명세를 뽑아 swagger ui로 띄우는 데서 시작하며, FastAPI는 /docs, Spring Boot는 springdoc-openapi를 씁니다.

3. Try it out은 실제 서버로 요청을 보내니 운영 환경에서는 공개 대상과 접근 권한을 정합니다.

Swagger는 OpenAPI 명세를 작성하고 보여 주는 도구 모음입니다. Swagger UI에서는 요청에 필요한 값과 응답 형식을 읽고 실제 API도 호출할 수 있습니다. 오늘은 Swagger 사용법을 UI 조작과 FastAPI·Spring Boot 설정, 문서 접근 관리 순서로 알아보겠습니다.

swagger란 무엇이고, OpenAPI와는 어떤 관계인가요

OpenAPI는 문서 형식이고, Swagger는 그 형식을 다루는 도구 이름입니다.

명세 형식의 원래 이름은 Swagger Specification이었는데 지금은 OpenAPI Specification으로 바뀌어 리눅스 재단 산하 OpenAPI Initiative가 관리합니다. swagger.io 문서에서도 Swagger는 오픈소스 도구 모음이고 그 중심에 OpenAPI 명세가 있다고 설명합니다.

2026년 10월 기준 OpenAPI 명세는 3.2 계열까지 나와 있습니다.

도구마다 지원하는 명세 버전이 다르므로 사용하는 프레임워크와 Swagger UI의 호환 범위를 확인합니다.

Swagger Editor는 코드보다 명세를 먼저 쓸 때 씁니다.

서버 코드가 아직 없는 단계에서 합의용 초안을 만들 때 swagger editor를 엽니다. YAML을 쓰는 대로 옆에 미리보기가 뜹니다.

swagger ui 사용법, 화면에서 바로 호출해 봅니다

첫째, 엔드포인트를 펼쳐 파라미터와 응답 형식을 봅니다.

swagger ui는 API를 태그별로 묶어 보여 주는데 항목 하나를 누르면 파라미터와 응답 스키마가 펼쳐집니다.

둘째, Try it out을 누르고 값을 넣습니다.

인증이 걸린 API라면 화면 위쪽 Authorize 버튼에서 토큰부터 넣어 둡니다.

셋째, Execute로 실제 응답을 확인합니다.

같은 요청을 재현하는 curl 명령과 응답 코드, 본문이 아래에 나옵니다. 요청을 저장해 반복하는 테스트까지 여기서 할 필요는 없으니 Postman 같은 호출 도구에 맡깁니다.

fastapi swagger 사용법, /docs가 기본으로 열립니다

타입 힌트만 달아 두면 FastAPI가 읽어 명세를 만들고 swagger ui 화면까지 알아서 붙여 줍니다.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}

pip install "fastapi[standard]"로 설치한 뒤 예제 파일을 main.py로 저장합니다. fastapi dev main.py로 띄우고 /docs를 열면 swagger ui가, /redoc을 열면 ReDoc 문서가 나옵니다. 명세 원본은 /openapi.json에 있습니다.

spring boot swagger 사용법은 springdoc-openapi로 시작합니다

springdoc 버전은 Spring Boot와의 호환 표에 맞춥니다. 아래는 Spring Boot 4용 3.x 예시이며, Spring Boot 3에서는 호환되는 2.x를 선택합니다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:3.1.1'

서버를 다시 띄워 /swagger-ui.html에 들어가 보면 컨트롤러가 이미 문서로 정리돼 있고 JSON 명세는 /v3/api-docs에 있습니다.

Swagger 운영 문서의 공개 범위는 어떻게 정할까요

내부 API 문서는 필요한 사용자에게만 엽니다.

FastAPI에서 docs_url=None만 주면 /openapi.json이 그대로 남기 때문에 openapi_url=None으로 명세와 기본 문서 경로를 함께 비활성화할 수 있습니다. Spring Boot라면 springdoc.api-docs.enabled=false와 springdoc.swagger-ui.enabled=false를 운영 프로필에 넣습니다.

공개 API 문서는 운영 중에도 제공할 수 있습니다. 문서 숨김과 API 자체의 인증·인가 검사는 별개이므로 서버에서 권한을 검증합니다. 기존 체크리스트 이미지는 내부 API를 비공개로 운영하는 경우의 점검표입니다.

Try it out은 연결된 서버에 진짜 요청을 보냅니다.

문서가 운영 주소에 붙어 있을 때 삭제 API를 실행하면 데이터가 정말로 지워집니다.

응답 모델과 예시를 코드에 적어 둬야 문서가 정확해집니다.

비워 두면 swagger ui에도 그 자리가 빈칸으로 남습니다.

배포 전에는 팀 안에서 이렇게 물어봅니다. 지금 swagger ui에 보이는 내용을 프론트엔드 개발자가 그대로 믿고 개발해도 되나요? 바로 답하지 못한다면 코드에 적은 정보부터 손봐야 합니다.

설정과 적용 조건을 더 살펴보려면 OpenAPI 명세 · FastAPI 문서 경로 설정 · springdoc 설정 안내를 참고해 보세요.

화면과 서버가 같은 명세를 바라보도록

똑똑한개발자는 사용자 화면과 백엔드·관리자 시스템을 함께 개발하는 팀입니다. API 문서는 두 영역이 주고받을 정보를 맞추는 데 쓰입니다. 문서 자동 생성 여부와 함께 요청·응답 예시, 인증 조건까지 개발 범위에 맞춰 정리할 수 있습니다.

API 문서와 실제 응답이 달라 개발이 막히시나요? 아래 링크로 문의해 주시면 명세와 구현 사이에서 확인할 항목을 함께 검토하겠습니다.

감사합니다. :)

📚 이어서 읽어보세요

• 노션 API 키 발급

• 구글 시트 API 연동 방법