[2021.07.12] Swagger란? + Spring Boot에 Swagger 시작하기

 

 

Swagger란?

 

개발자가 REST API 서비스를 설계, 빌드, 문서화할 수 있도록 하는 프로젝트

• Springboot에서 Swagger를 사용하면, Controller에 명시된 어노테이션을 해석하여 API문서를 자동으로 만들어준다.
• http://localhost:8080/cameo/swagger-ui.html로 접근하면 swagger가 만들어주는 페이지에 접근할 수 있다.
• API들이 가지고 있는 스펙(spec)을 명세, 관리할 수 있는 프로젝트/문서
• API 사용 방법을 사용자에게 알려주는 문서

 

Swagger 사용 용도

• 다른 개발팀과 협업을 진행할 경우
• 이미 구축되어있는 프로젝트에 대한 유지보수를 진행할 경우
• 백엔드의 API를 호출하는 프론트엔드 프로그램을 제작할 경우

 

장점

• API 정보 현행화 가능
• API를 통해 Parameter, 응답 정보, 예제 등 Spec 정보 전달이 용이함
• 실제 사용되는 Parameter로 테스트 가능
• 따로 로그인 하지 않아도 된다!

 

 

🔽 참고한 링크

Swagger란?

Swagger란

 

---

Swagger 시작하기

 

 

1. properties에 context-path와 port지정

 

port는 5000번대 이상의 내가 원하는 번호로 설정 (난 8097로 설정!)

 

context-path는 8097 port를 사용하는 프로젝트의 경로 이름! (난 skeloron으로 설정!)

그러니까 혹여 다른 사람과 같은 넘버의 port를 사용하더라도 추가적인 path를 사용해줌으로서 차별화를 둠!

 

2. SwaggerConfig.java 클래스 작성

 

3. pom.xml의 dependency 확인(의존성 추가)

 

4. Swagger-UI 확인

아래와 같은 방법으로 작성해 주소창에 넣고 엔터해준다.

http://localhost:8080/{your-app-root}/swagger-ui.html

따라서, 나는 http://localhost:8080/skeleton/swagger-ui.html

 

 

Swagger UI 적용된 모습

 

내가 만든 모든 Controller가 보이는 모습

 

 

그 중 AccountController를 클릭해보았을 때의 모습.

 

 

• 위 사진의 오른쪽에 적힌 '회원탈퇴'는 backend의 AccountController단에서 @ApiOperation을 통해 value값으로 넘겨준 것!
• Implementation Notes에 적힌 내용 역시 같은 어노테이션에서 notes값으로 넘겨준 것 이다.

 

[참고] @ApiOperation란?
요청 URL 에 매핑된 API 에 대한 설명
 - value 값 : 제목과 같은 느낌
 - notes 값 : 상세내용과 같은 느낌