30.Spring, 서비스의 문서화에 대한 필요성을 알아보고 간단한 샘플프로그램을 만들어 보자.

서비스에 대한 문서화의 필요성?

서비스 공급자는 서비스의 소비자에게 서비스를 제공할 때, 세부 사항을 정의 해주면 좋음.

주요 세부 내용은 아래와 같음.

하나, 서비스를 호출하는 방법 및 서비스 요청을 위한 URI는 무엇인가?

둘, 서비스요청을 위한 형식은 어떻게 되어야 하는가?

셋, 서비스를 요청 했을 때, 어떤 응답 메시지가 발생하는가 ?

기타 등등.

 

그럼, 서비스에 대한 문서화는 어떻게 하면 좋을까?

가장 인기 있는 옵션은 바로, 스웨거(swagger) 를 사용하는 것.

 

그럼, 스웨거에 대해서 알아보자.

스웨거(swagger) 란?

Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset.

간단히 말하면, Swagger 오픈 소스 및 전문 툴셋을 사용하면, 사용자, 팀 및 기업을위한 API 개발을 간소화할 수 있음.

다시말해서, API에 대한 RESTful 문서를 작성해서 모든 자원 및 조작을 인간 및 기계가 읽을 수 있는 형식으로 자세하게 설명해 쉽게 개발 및 통합할 수 있는 기능을 제공함.

참고페이지

http://swagger.io

 

그럼, 스웨거의 장점은?

스웨거를 사용하면, RESTful 서비스 코드에서 바로 스웨거 문서를 생성할 수 있음.

즉, 코드와 문서가 항상 동기화됨.

스웨거 UI 를 사용하면, 어플리케이션에 통합돼 사람이 읽을 수 있는 문서를 제공함.

 

그럼, 스웨거를 사용하려면 어떻게 해야 할까?

첫째, 아래와 같이 pom.xml 에 의존성을 추가함.

 

둘째, 스웨거 문서를 활성화하고 생성하기 위해서 아래와 같이 환경설정 클래스를 추가함.

설명

@Configuration 어노테이션

스프링 구성 파일을 정의함.

@EnableSwagger2 어노테이션

스웨거 지원을 가능하게 함.

Docket

스웨거 Spring MVC 프레임워크를 사용해 스웨거 문서 생성을 설정하는 간단한 빌더 클래스

new Docket(DocumentationType.SWAGGER_2)

스웨거 2를 사용할 스웨거 버전으로 설정함.

.apis(RequestHandlerSelectors.any()).paths(PathSelectors.any())

문서의 모든 API와 경로를 포함함.

그럼, 어플리케이션을 실행해서 정상적으로 스웨거가 동작하는지 확인해 보자.

하나, 어플리케이션 구동

둘, 아래 URI를 요청해보자

http://localhost:8080/v2/api-docs

위와 같이 정상적으로 스웨거가 작동함을 알 수 있음.

 

그럼, 스웨거 UI 에 대해서 알아보자

아래 URI 를 통해서 스웨거 UI로 문서를 볼 수 있음.

http://localhost:8080/swagger-ui.html

위와 같이

코드를 기반으로 사용자가 보기 쉽게 Api 문서가 자동 작성됨을 확인할 수 있음.

그리고 아래와 같이 Controller 를 클릭하면 각 Controller가 지원하는 요청 메소드 및 URI 목록도 보여줌.

그럼, POST 관련 /thubuser를 선택해서 상세내용을 확인해보자

위와 같이 중요사항을 보여줌.

Parameters

요청 본문을 포함해 모든 주요 파라미터를 보여줌.

Parameter Type

요청 본문에 대해 예상되는 구조를 보여줌.

Response Message

서비스에서 반환한 여러가지 HTTP 상태코드를 보여줌.

그리고, 위의 value 값을 채우고 "Try it out!" 버튼을 클릭하면,

아래와 같이 자체적으로 테스트도 가능함.

다시 정리하자면,

스웨거 UI를 사용하면, 많은 노력없이도, 개발한 API 에 대한 서비스 정의를 공개 할 수 있는 장점이 있음.

그리고, 추가 어노테이션을 이용하면, 문서를 커스텀하게 내용을 개선 할 수 있음.

그럼, 간단하게 Controller에 아래 어노테이션을 추가해보자

package com.example.rest.demo.controller; import com.example.rest.demo.bean.ThubUser; import com.example.rest.demo.exception.ThubUserNotFoundException; import com.example.rest.demo.service.ThubUserService; import io.swagger.annotations.ApiOperation; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.hateoas.EntityModel; import org.springframework.hateoas.server.mvc.ControllerLinkBuilder; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.validation.BindingResult; import org.springframework.web.bind.annotation.*; import javax.validation.Valid; @RestController public class ThubUserController { private final static int ZERO = 0; @Autowired private ThubUserService thubUserService; @ApiOperation( value = "별명으로 유저를 검색하는 기능을 제공함", notes = "일치하는 유저 정보가 반환됨", response = ThubUser.class, responseContainer = "ThubUser", produces = "application/json" ) @GetMapping("/thubusers/{nickname}") public ThubUser retrieveThubUser(@PathVariable String nickname) { ThubUser thubUser = thubUserService.retrieveThubUser(nickname); if(thubUser == null) { throw new ThubUserNotFoundException("User not found!"); } return thubUser; } ...(생략)... }

설명

@ApiOperation(value = "별명으로 유저를 검색하는 기능을 제공함")

서비스 요약으로 생성됨.

notes = "일치하는 유저 정보가 반환됨"

서비스 설명으로 생성됨.

produces = "application/json"

서비스 문서의 "produce" 절을 커스텀하게 함.

그럼, 무엇이 달라졌는지 AS-IS 와 TO-BE 를 비교해보자

AS-IS

TO-BE

위에 설명 했던 부분들이 개선되었음을 확인할 수 있음.

서비스 요약, 설명, "produce" 절 기타등등.

 

그럼, 스웨거관련 문서를 커스텀하게 개선시킬 때, 사용하는 주요 어노테이션에 대해서 간단하게 알아보자.

@Api

클래스를 스웨거 리소스로 표시함

@ApiModel

스웨거 모델에 대한 추가 정보를 제공함.

@ApiModelProperty

모델 속성의 데이터를 추가하고 조작함.

@ApiOperation

특정 결로에 대한 Operation or HTTP 메소드를 설명함.

@ApiParam

Operation 파라미터에 대한 추가 메타 데이터를 추가함.

@ApiResponse

Operation 의 응답예를 설명함.

@ApiResponses

여러 ApiResponse 객체 목록을 허용하는 래퍼.

@Authorization

Resource or Operation 에 사용되는 권한 부여 체계를 선언함.

@AuthoriztionScope

OAuth2 인증 범위에 대해서 설명함.

@ResponseHeader

응답의 일부로 제공될 수 있는 헤더를 나타냄.

 

마지막으로, 스웨거는 연락처 / 라이센스 및 기타 정보와 같은 일련의 서비스에 대한 고급정보를 커스텀하는 데 사용할 수 있는 스웨거 정의 어노테이션을 알아보자.

@SwaggerDefinition

생성된 스웨거 정의에 추가될 정의 레벨 속성

@Info

스웨거 정의를 위한 일반 메타 데이터

@Contact

스웨거 정의를 위해 연락할 사람을 설명하는 속성

@License

스웨거 정의에 대한 라이선스를 설명하는 속성

​

결론

스웨거(swagger) 란?

Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset.

간단히 말하면, Swagger 오픈 소스 및 전문 툴셋을 사용하면, 사용자, 팀 및 기업을위한 API 개발을 간소화할 수 있음.

다시말해서, API에 대한 RESTful 문서를 작성해서 모든 자원 및 조작을 인간 및 기계가 읽을 수 있는 형식으로 자세하게 설명해 쉽게 개발 및 통합할 수 있는 기능을 제공함.

스웨거의 장점은?

스웨거를 사용하면, RESTful 서비스 코드에서 바로 스웨거 문서를 생성할 수 있음.

즉, 코드와 문서가 항상 동기화됨.

스웨거 UI 를 사용하면, 어플리케이션에 통합돼 사람이 읽을 수 있는 문서를 제공함.

오늘도 서비스 코드에서 바로 문서를 생성할 수 있는 스웨거에 대한 지식 마술(?) 한가지 획득완료! 감사합니다. ^^

---

오늘의 명언 한마디

사람들에게 완벽하게 보이려고 하면 할수록 사람들은 당신에게서 멀어진다.

사람들이 당신에게 호감을 갖고, 당신에게 자꾸만 다가서고자 하는 건, 당신 또한 자신과 같은 인간이라는 사실을 끊임없이 확인하는 작업을 통해 이루어진다.

레일 라우즈지음, "사람을 얻는 기술" 중에서..

---

오늘의 영어 한마디

No one dresses better than Jenny.

아무도 옷을 입지 않아 / 더 잘 / Jenny 보다

설명

부정대명사

사람이나 사물을 막연히 나타내는 대명사를 말함.

위의 one 은 일반사람을 나타내는 경우에 쓰임.

참고로 no one 은 단수로 none 은 복수로 취급됨.

"better than" 은 비교급을 말함.

즉, Jenny 보다 더 잘 옷을 입지 않음을 나타냄.

---

오늘의 민법 한마디

제1편 총칙 / 제5장 법률행위 / 제4절 무효와 취소

제140조(법률행위의 취소권자)

취소할 수 있는 벌률행위는 제한 능력자, 착오로 인하거나, 사기, 강박에 의하여 의시표시를 한 자, 그의 대리인 또는 승계인만이 취소할 수 있다.

 

---

나의 목표 및 다짐을 항상 내곁에 두기.

목표

나의 강점을 바탕으로 나의 일을 잘해냄으로써 타인과 사회를 아릅답게 만든다.

현재 내가 가진 능력으로 누군가에 도움이 될 수 있을까? 에 대해서 항상 생각하기

 

목표를 이루기 위한 실천방안

꾸준한 블로깅/기록법/독서법으로 넘버원이 아닌 온리원이 되보자.

천사불여일행(千思不如一行)을 항상생각하며 체화 및 각인시키자.

"천번 생각하는것보다 한번 행동하는 것이 더 중요하다."

기기일약 불능십보(騏驥一躍 不能十步) / 노마십가 공재불사(駑馬十駕 功在不舍)

천리마도 한번에 열걸음을 뛸 수 없고, 느리고 둔한말이라도 열흘이면 하룻길을 간다.