swaggo/swag

어떤 프로젝트인가요?

핵심 기능

• 01Swagger 2.0 스펙을 JSON, YAML, Go docs 패키지 형식으로 생성합니다.
• 02Go 핸들러 함수 위에 작성하는 주석 어노테이션으로 엔드포인트를 문서화합니다.
• 03요청 파라미터, 응답, 헤더, 보안 정의, 태그를 지원합니다.
• 04struct 필드 태그에서 예제, 검증 규칙, enum을 읽어옵니다.
• 05Gin, Echo, Fiber, net/http, chi 및 기타 프레임워크용 미들웨어를 제공합니다.
• 06어노테이션 주석의 형식을 정리하는 swag fmt 명령어를 포함합니다.

활용 사례

• 별도의 OpenAPI 파일을 직접 관리하지 않고 Go REST 서비스의 API 문서를 생성합니다.
• Gin 또는 Echo 백엔드에서 인터랙티브한 Swagger UI 페이지를 제공합니다.
• CI 빌드 중 핸들러 코드와 API 문서를 동기화합니다.

빠른 시작

1. 1

   Go로 swag CLI를 설치합니다

   go install github.com/swaggo/swag/cmd/swag@latest
2. 2

   Go 소스 코드 주석에 API 어노테이션을 추가합니다

3. 3

   main.go가 있는 프로젝트 루트에서 swag init을 실행해 문서를 생성합니다

   swag init

사용 전 알아둘 점

• !Swagger 2.0 문서만 생성하며 OpenAPI 3.x는 지원하지 않습니다.
• !Go 주석에 어노테이션을 작성해야 하며, 변경 후 문서를 다시 생성해야 합니다.

토픽

자주 묻는 질문

swag은(는) 무엇인가요?

Go 소스 코드 주석의 어노테이션으로 Swagger 2.0 API 문서를 생성하는 Go 도구입니다. Swag는 핸들러 함수와 struct 정의 등에 작성된 특수 형식의 주석을 파싱해 swagger.json, swagger.yaml, docs.go 파일로 Swagger 2.0 문서를 생성합니다. 개발자는 핸들러 위에 @Summary, @Param, @Success, @Router 같은 어노테이션을 추가한 뒤 swag init을 실행해 스펙을 다시 생성합니다.

swag은(는) 무료로 사용할 수 있나요? 라이선스는 무엇인가요?

swag은(는) MIT 라이선스의 오픈소스입니다. 상업용 제품에 사용하기 전에 라이선스 조건을 확인하세요.

swag은(는) 아직 유지보수되고 있나요?

6개월 이내 업데이트. swag의 마지막 커밋은 2026년 9월 30일입니다.

swag은(는) 어디에 사용할 수 있나요?

별도의 OpenAPI 파일을 직접 관리하지 않고 Go REST 서비스의 API 문서를 생성합니다. Gin 또는 Echo 백엔드에서 인터랙티브한 Swagger UI 페이지를 제공합니다. CI 빌드 중 핸들러 코드와 API 문서를 동기화합니다.

swag는 어떻게 설치하나요?

Go로 swag CLI를 설치합니다: go install github.com/swaggo/swag/cmd/swag@latest Go 소스 코드 주석에 API 어노테이션을 추가합니다 main.go가 있는 프로젝트 루트에서 swag init을 실행해 문서를 생성합니다: swag init

swag은(는) 어디서 받을 수 있나요?

소스 코드와 설치 방법은 GitHub에 있습니다: https://github.com/swaggo/swag