우아한테크코스 생존기 (8)(Swagger를 이용한 API명세서 관리하기)

스웩~

오늘은 Swager를 활용한 API문서를 관리하는 법을 배우겠습니다.

 

 

먼저 swagger를 사용하려면 의존성을 추가시켜야하는데

Springfox와 Springdoc 두가지가 있는데

 

Springfox와 springdoc는 둘 다 Swagger를 지원하기 위한 Spring 기반의 프로젝트입니다.

Swagger는 API 문서를 자동으로 생성하고 표시하는 도구로 널리 사용되고 있습니다.

이 두 프로젝트는 Swagger를 통해 API 문서화를 쉽게 구현할 수 있도록 도와주는 역할을 합니다.

 

하지만

Springfox와 springdoc는 구현 방식과 사용법에서 일부 차이가 있습니다.

 

 

Springfox:

• Springfox는 Swagger v2(Swagger UI 2.x)를 기반으로 한 라이브러리입니다.
• 기존의 Swagger 1.x와 호환성을 유지하면서도 Swagger 2.x의 새로운 기능을 활용할 수 있도록 제공됩니다.
• Springfox는 주로 Spring Boot 1.x 프로젝트에서 사용되었으며, Java 기반의 애너테이션을 사용하여 API 문서를 작성합니다.
• 최신 버전의 Springfox는 OpenAPI 3.0을 지원하기 위한 노력이 이루어지고 있습니다.

 springdoc:

• springdoc는 OpenAPI 3.0 기반의 API 문서화를 지원하는 라이브러리입니다.
• Spring Boot 2.x와 호환되며, 스프링 프레임워크의 애너테이션과 함께 사용됩니다.
• springdoc는 Swagger UI 대신 ReDoc를 사용하여 API 문서를 표시할 수 있습니다. ReDoc는 Swagger UI보다 간결하고 모던한 디자인을 제공합니다.
• springdoc는 기본적으로 JSON 문서를 생성하지만, 추가적인 설정을 통해 YAML 문서를 생성할 수도 있습니다.

차이점 : 주요한 차이점은 Springfox가 Swagger v2를 사용하고, springdoc가 OpenAPI 3.0을 사용한다는 것입니다. OpenAPI 3.0

Swagger 2.x보다 더욱 강력하고 유연한 스펙이며, API문서 작성에 있어서 다양한 기능과 옵션을 제공합니다.

 

 

그래서 저는 사진과 같이 Springdoc을 의존성을 주입 시켰습니다.

 

 

다음으로는 컨트롤러는 만들어야하는데

어떻게 데이터를 주입받을지 Request와 Response를 미리 정해주고 

이전과 똑같이 Controller를 만들어주면 됩니다.

 

Application을 실행시켜주면 사진과 같이 정의해준 API를 확인할 수 있습니다.

 

 

Swagger의 좋은 점은 Postmam을 사용하지 않고 데이터를 보낼수 있다는 점입니다.

보내고 싶은 요청을 클릭하면 아래 사진과 같이 Try it out을 누르면 보낼 수 있는 화면이 나오는데

GET같은 경우는 바로 Execute를 누르면

다음과 같이 어떤 데이터가 넘어왔는지, 상태코드로 어떤 값이 넘어왔는지를 확인할 수 있습니다.

 

 

POST와 같은 값을 지정하고 데이터를 날려주는 경우에는

값을 넣어주고 Execute를 누르면 원하는 서버로 데이터를 전송할 수 있고,

테이터가 잘 전송됐는지 또한 확인할 수 있습니다.

(ex.200 ok,201 created... 등등)

 

마지막으로 Swagger를 커스터마이징할 수 있는데  아래와 같이 디폴트 설정이 정공하는 Swagger페이지만으로
충분히 API를 관리할 수 있지만 커스터마이징을 통해 꾸밀 수 있습니다.

 

 

~꾸미는중~

 

 

위 사진 처럼 Configuration으로 그룹을 지정해서 다시 Swagger를 보게되면 밑에 사진과 같이

페이지 상단에 그룹으로 API를 확인할 수 있습니다!

 

 

 

 

 

여러분도 편하게 API를 관리하세요~~