Swagger을 통해 OpenAPI 문서화하기

OAS에 대해 알아보기

OAS에 대해 알기 전 선행되어야 하는 개념들이 있다

 

REST

Representational State Transfer의 약자로 자원을 이름으로 구분하여 해당 자원의 상태를 주고 받는 모든 것

HTTP Method를 통해 CRUD Operation을 적용하는 것을 의미한다

1. EX) DB의 게시글 정보가 자원일 때, posts로 표현함

RESTful API란?

• REST 기반으로 서비스 API를 구현한 것

기본 규칙

• resource는 동사보다는 명사를, 대문자보다는 소문자를 사용한다
• resource의 도큐먼트 이름으로는 단수 명사를 사용해야 한다
• resource의 컬렉션 이름으로는 복수 명사를 사용해야 한다
• resource의 스토어 이름으로는 복수 명사를 사용해야 한다
• 자원에 대한 행위는 HTTP Method(GET,PUT,POST,DELETE)
• URL에 HTML Method가 들어가면 안된다
• URL에 행위에 대한 동사 표현이 들어가면 안된다
• 경로 부분 중 변하는 부분은 유일한 값으로 대체한다

HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍쳐 스타일

 

그럼 여기서 HTTP 프로토콜이란?

HTTP(Hypertext Transfer Protocol)는 인터넷상에서 데이터를 주고 받기 위한 서버/클라이언트 모델을 따르는 프로토콜 -> 쉽게 말하면 링크기반으로 데이터에 접속하겠다는 의미

이제 OAS로 넘어가보자

 

OAS란?

• OpenAPI Specification은 RESTful API를 기술하는 표준으로 서비스에서 제공하는 API의 기능과 End Point를 개발자나 시스템이 자동으로 발견하고 처리하는데 필요한 정보 제공한다
• Json이나 yml형식으로 기술해야한다

필요한 이유(예시)

상황: 회사에서 제품 주문 정보를 제공하는 API를 개발하려고 할 때 여러 개발자와 팀이 이 API를 사용하게 됩니다.

필요성: 다양한 개발자가 이 API를 사용하려면 API의 기능, 엔드포인트, 요청 및 응답 형식 등을 명확히 이해해야 한다. 이를 위해 OAS를 사용하여 API를 문서화하면, 다른 개발자들은 자동으로 생성된 문서를 통해 API 사용 방법과 예제를 확인할 수 있다.

 

그럼 지금 나의 URL은 RESTful한가?

특정게시물 : http://localhost:8080/postview/10

게시판 page별 : http://localhost:8080/list?page=0

글작성 페이지 : http://localhost:8080/posts

로그인 : http://localhost:8080/Login

회원가입 : http://localhost:8080/SignUp

마이페이지 : http://localhost:8080/MyPage

규칙을 잘 준수하고 있다.

 

 

 

이제 직접 실습해보자

먼저 Build.gradle에

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

를 추가하고 프로젝트를 작동시킨다

그 후 http://localhost:8080/swagger-ui/index.html에 접속하면

이제 프로젝트의 코드들에 @Operation @Tags 어노테이션을 추가한다

 

이런 식으로 추가해주면

이렇게 나오게 된다.

거기에 스키마 설정까지 해주게 된다면

성공이다

 

 

후기

Swagger-UI를 통해 API를 쉽게 문서화할 수 있다. 복잡한 프로젝트일수록 매우 필요한 작업이 되지 않을까 싶다. 팀프로젝트나 과제를 하면서 Swagger을 사용한 사람들은 보기 매우 드물었는데, 앞으로 팀프로젝트를 진행하며 Swagger을 꾸준히 사용하기로 다짐해본다.

 

 

 

 

 

 

참고 : https://adjh54.tistory.com/72