API 문서화를 위한 Swagger와 Spring Rest Docs 비교

Swagger란?

API 문서를 자동으로 만들어주는 라이브러리입니다.

REST API를 편리하게 문서화해주고, 이를 통해 편리하게 API를 호출해보고 테스트할 수 있는 프로젝트입니다.

 

이를 활용하여 협업하는 클라이언트 개발자에게도 Swagger 만 전달해주면 API Path와 Request , Response 값 및 제약 등을 한 번에 알려줄 수 있습니다.

 

 

Swagger 예시

글로만 보면 이해하기 어려울 수 있기 때문에 실제로 예시를 보여드리겠습니다.

 

아래의 사이트에서 직접 활용해볼 수 있습니다.

https://petstore.swagger.io/?_ga=2.58706851.880875351.1654000882-1005427767.1652498303 

Swagger UI

 

 

PET API 예시

pet 과 관련된 API들이 문서화되어 있음

여기에서 GET /pet/{petid}를 구체적인 예시로 살펴보겠습니다.

 

우선 URL만 보았을 때 petId를 기반으로 펫의 정보를 가져오는 API 같습니다.

 

실제로 설명으로도 "Find pet by ID"라고 적혀있습니다.

 

GET /pet/{petId} 구체 예시

해당 API를 클릭해보면 다음과 같은 화면이 나타나게 됩니다.

 

가장 위에 Return a single pet이라는 구문이 보입니다.

 

이를 통해 "하나의 pet을 반환하는구나"라고 생각할 수 있습니다.

 

그리고 Parameters(인자)로는 petID가 주어지고 이는 Integer값입니다.

 

Responses(응답)은 200 suceessful operation, 400 Invalid ID supplied, 404 Pet not found가 존재합니다.

 

 

 

 

Parameters부분에 Try it out 버튼을 누른 후 2를 입력하고 Excute를 눌러봅니다.

 

아마도 2번 ID를 가진 pet이 존재한다면 해당 pet의 정보를 가져올 것이며 존재하지 않는다면 404 에러가 발생할 것입니다.

인자를 2로 세팅 후 API 호출

 

정상적으로 200 OK 응답이 도착하였습니다.

200 OK 응답

 

이번에는 200을 입력해보겠습니다.

인자를 200으로 세팅 후 API 호출

404 Not Found 발생

이번에는 200에 해당하는 pet이 존재하지 않아 404 에러가 발생하였습니다.

 

이처럼 Swagger를 활용한다면 API를 테스트해보거나 클라이언트 개발자 또한 API를 이해하기 쉬워집니다.

 

SpringRestDocs란?

만약 사전에 정의된 스펙 문서에 대한 정보를 그때마다 업데이트하지 않고 실수로 누락하는 경우가 증가한다면 협업을 하는데 피로가 증가할 수 있습니다.

 

이런 상황에서 우리가 구현한 API 서비스를 깔끔한 HTML 형태의 문서로 생성해주는 프레임워크가 바로 SpringRestDocs입니다.

 

하지만 이 프레임워크를 도입하기 위해 매우 중요한 조건이 있습니다.

• 테스트 코드를 작성해야 한다.
• 테스트 코드 검증을 통과해야 한다.

이는 곧 테스트 주도 개발의 법칙을 준수하며 신뢰성 있는 서비스 개발을 지향해 갈 수 있습니다.

 

 

SpringRestDocs예시

https://ahndy84.tistory.com/27?category=339592

TestCase를 기반으로 API 명세 문서가 깔끔하게 서비스됩니다.

그리고 왼쪽 상단에는 다음과 같이 색인목록도 함께 표시가 됩니다.

https://ahndy84.tistory.com/27?category=339592

 

둘 중에 어떤 것을 선택할까?

• SpringRestDocs 
  장점
  제품 코드에 영향이 없다.
  테스트가 성공해야 문서작성이 된다.
  
  단점
  적용하기 어렵다.
• Swagger
  장점
  API를 테스트할 수 있는 화면을 제공한다.
  적용하기 쉽다
  
  단점
  제품코드에 어노테이션을 추가해야 한다.
  제품 코드와 동기화가 안될 수 있다.

 

결론

API 문서의 목적은 개발하는 스펙을 정의하는 것입니다.

 

Swagger는 API 동작을 테스트하는 용도에 더 특화되어 있습니다.

 

SpringRestDocs는 좀 더 깔끔 명료한 문서를 만들 수 있습니다.

 

따라서 Spring Rest Docs를 활용하여 API 문서를 만들어 보겠습니다.

 

 

출처

https://swagger.io/

API Documentation & Design Tools for Teams | Swagger

https://ahndy84.tistory.com/27?category=339592 

나의 첫 SpringRestDocs 적용기 part 1

https://techblog.woowahan.com/2597/

Spring Rest Docs 적용 | 우아한형제들 기술블로그