뚝딱뚝딱

↓↓↓이전내용

2024.01.10 - [Web Application/Backend] - [REST API] Spring Boot로 REST API 프로젝트 (8) - JUnit TEST controller 계층 test 예제

지금까지 만들어온 rest api의 document를 생성해보자. 

💡 API Documentation

개발자나 api 사용자에게 api 내 서비스와 상호작용하는 방법을 설명하는 문서이다.
특히 협업할 때 api 문서를 참고하여 api의 동작을 이해하고, 어떤 데이터를 보내고 어떤 응답을 기대하는지 확인하여 여러 개발자가 함께 작업하는데 도움을 준다.

이러한 api 문서를 자동으로 생성해주는 프레임워크가 있는데, 바로 Swagger이다.

💡 Swagger

swagger는 rest api를 설계하고 문서화하는데 매우 효과적이고, 개발자 커뮤니티에서 많이 사용되고 있다.

따라서 swagger는 개발자가 api를 개발하고, api간의 상호작용을 정의해주는 api 문서를 자동으로 생성해주는 도구이다.

스프링 부트에서 swagger를 사용하려면 springfox 의존성을 추가해 주면 된다. (자세한건 아래에서)

swagger의 사용
- api design
- api development
- api testing
- api mocking
- api governance
- api monitoring
- api documentation ✔

우리는 프론트/ui 디자이너와 일 할 때 api document를 가지고 이 request가 어떻게 동작하게 되는지를 보다 쉽게 이해 시킬 수 있다.

또한 이 메서드의 파라미터는 몇개인지, url은 무엇인지.. 등등

어떻게 response를 생성하고 client에게 전달하는지 그 과정을 설명해주는것이 api 문서이다.

만약 document에 수정이 필요하더라도 swagger를 통하면 쉽게 수정하고 바로 반영되기 때문에, 변경된 사항을 바로 확인하고 업무를 지속할 수 있다는 강력한 장점이 있다.

이제 spring boot에서 swagger를 사용하여 api 문서를 생성해보자.

💡 swagger 사용을 위한 종속성 추가

1. build.gradle

implementation 'io.springfox:springfox-boot-starter:3.0.0'
implementation 'io.springfox:springfox-swagger-ui:3.0.0'

swagger를 사용하기 위해서 springfox-boot-starter 의존성을 추가해준다. 

그리고 swagger-ui도 추가해준다. swagger-ui는 api 문서를 사용자 친화적으로 보기 편리하게 만들어진 브라우저인데, API의 엔드포인트, 매개변수, 응답 등에 대한 정보를 시각적으로 볼 수 있으며, 테스트할 수도 있다.

위 코드를 build.gradle의 dependency 안에 추가해준다.

주의할 점은 두개의 버전이 동일해야 한다는 점!!

2. yml

  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

이 코드는 yml파일에서 Spring MVC 프레임워크의 경로 매칭 전략을 지정하는 데 사용된다.

이 설정은 경로 매칭 전략을 ant_path_matcher로 설정한 것인데, spring의 ant 스타일의 경로 패턴 매칭 전략을 사용한다는 것을 의미한다.

이러한 mvc 경로 매칭은 URL과 컨트롤러 메소드 사이의 매핑을 결정하는 프로세스이다.

사용자가 특정 URL로 요청을 보내면, spring mvc는 해당 요청을 어떤 컨트롤러 메소드와 매핑할지를 결정하고 실행한다.

ant 스타일의 경로 패턴은 와일드카드(*)를 사용해서 유연한 경로 매칭을 가능하게 하는데, 이를 이용해서 URL을 매칭한다.

예를 들어서 /cloudvendor/*는 /cloudvendor/ 또는 /cloudvendor/c5 와같은 URL과 일치할 수 있다.

따라서 해당 URL과 일치하는 메소드를 매핑하게 된다.

위와 같이 swagger를 사용할 준비가 되었으면, spring boot를 실행해본다.

실행하면 api 문서도 자동으로 만들어진다.

8080 포트에서 성공적으로 연결되었다.

💡 POST MAN에서 api 문서 생성 확인

post man에서 실행 후 생성된 api document를 확인해보자.

일단 post를 통해 C5를 생성해보자. 완료

get을 통해 C5를 검색하고 읽어보자. 완료

새로운 get request를 만들어서 경로를 http://localhost:8080/v3/api-docs 로 지정해주면, 문서를 읽을 수 있다.

여기서 v3은 version 3라는 뜻. 우리는 3.0.0을 사용하기 때문에! (2.x이면 v2)

이 request의 이름은 Swagger document라고 지정해주자.

send를 누르니, 아래와 같은 response가 출력되었다.

openapi의 버전은 3.0.3

생성된 api 문서의 title은 Api Documentation이고, 그 아래와 같은 내용으로 문서가 구성되어 있다.

💡 swagger-ui

위와 같이 확인하니 잘 와닿지 않는다.

그런데 Swagger는 사용자에게 편리한 UI 페이지를 제공하여 문서를 확인할 수 있게한다. 

그게 바로 swagger-ui이다.

http://localhost:8080/swagger-ui/ 이 링크를 웹에 입력하여 확인해보자.

swagger-ui 페이지를 보니, postman에서 response에 있던 내용들로 문서가 시각적으로 제공되고있음을 확인할 수 있다.

이렇게 swagger가 자동 생성해준 문서 내용을 내가 커스텀해서 수정할 수도 있다.

현재는 너무 일반적인 정보뿐이고, cloud vendor api의 특성에 맞게 디테일한 것을 추가하고 수정할 수 있다.

basic-error-controller(패키지 정보)를 지우고, api의 주된 controller 내용만 보이게 하며, api 정보도 cloud vendor로 변경해보려 한다.

💡 api 문서 커스텀하기

spring boot application이 시작되는 지점에다가 docket bean을 생성함으로써 커스텀을 진행할 수 있다.

docket이란?

docket은 swagger를 사용하여 api 문서를 생성하기 위한 설정 클래스로, api 문서의 어떤 정보를 어떻게 표시할지 등을 설정해주기 위한 용도이다.

즉, 실행 컨트롤러 클래스 하에 아래 코드를 추가해준다.

@Bean
	public Docket swaggerConfiguration(){
		return new Docket(DocumentationType.SWAGGER_2)
				.select()
				.paths(PathSelectors.ant("/cloudvendor/*"))
				.apis(RequestHandlerSelectors.basePackage("com.mstoy.restdemo"))//패키지를 그대로
				.build()
				.apiInfo(apiCustomData()); //인자로 ApiInfo를 주어야 함, 아래에서 하나 생성해주고 넣어줄것임
	}
	private ApiInfo apiCustomData(){//여기다가 costom 파라미터들을 설정해주면 됨
		return new ApiInfo(
				"Cloud Vendor API Application",
				"Cloud Vendor Documentation",
				"1.0",
				"Cloud Vendor Service Terms",
				new Contact("Minseo Kim", "https://github.com/minseo0102",
						"sk49058275@gmail.com"),
				"Minseo 0102 License",
				"https://github.com/minseo0102",
				Collections.emptyList()
		);

	}

• public Docket swaggerConfiguration()
  - Docket을 반환하는 swaggerConfiguration 함수를 정의한다.
  - Docket을 반환하기 때문에 Docket 객체를 동적 할당해준뒤, return한다.
  - 인자로는 문서 타입을 넣어주는데, swagger2로 한다.
  - yml 파일에서 우리는 ant 스타일의 경로 패턴을 사용하기로 했기때문에, 경로 paths는 "/cloudvendor/*"로 설정하여 cloudvendorController에 있는 모든 crud 메서드와 매핑되도록 한다.
  - apis(RequestHandlerSelectors.basePackage("com.mstoy.restdemo"))를 통해 해당 패키지에 속한 컨트롤러만 문서화 하도록 해서 basic-error-controller가 뜨지 않도록 하였다.
  - api 문서의 내용을 커스텀하기 위해서 apiInfo에 내가 설정해준 내용을 담아야 하는데, 이는 ApiInfo라는 객체에 담아서 인자로 전달할 수 있다. 따라서 아래 private으로 ApiInfo 객체를 반환하는 메서드 apiCustomData()를 만들어 주었다.
• private ApiInfo apiCustomData()
  - ApiInfo 객체를 동적 할당하여 반환하도록 하고, 인자로 커스텀할 정보를 담아준다.
  - 어떤 인자들을 담을 수 있는지는 ApiInfo 클래스를 참고하여 확인할 수 있다.
  - title(string), description(string), version(string), termsOfServiceUrl(string), contact(Contact), license(string), licenseUrl(string), vencorExtentions(collection) 총 8개의 파라미터가 있다.
  - title : api 문서의 제목이다. 프로젝트 또는 api의 이름이 여기에 들어간다. cloudvendor api이므로 "Cloud Vendor API Application"로 설정해주었다.
  - description : api 문서에 대한 간단한 설명이다. api의 목적이나 주요 기능을 적어준다.
  - version : api의 현재 버전이다. 변경될때마다 버전을 높혀줄 수 있다. 1.0을 시작으로 한다.
  - termsOfServiceUrl : 서비스 이용 약관의 URL을 지정한다. api 사용자에게 약관을 제공하고자 할때 활용한다.
  - contact : api에 대한 연락처이다. 담당자 이름, 이메일, 웹사이트를 제공한다. 내 이름과, 이메일, 깃허브 주소를 적었다.
  - license : api의 라이센스 정보다.
  - licenseUrl : 라이센스에 대한 url이다. 라이센스에 대한 자세한 정보를 사용자에게 제공할 때 활용한다. 내 깃허브 주소를 적어주었다.
  - vendorExtensions : swagger 명세에서 제공하는 기능 외 추가적인 속성을 지정할 때 사용한다. 그냥 빈 collection으로 넣어주었다.

커스텀 할 apiInfo에 대해서는 인자로 ApiInfo를 넣어주어야 하기 때문에, private으로 ApiInfo 객체를 반환하는 메서드를 선언해서 원하는 정보로 커스텀 해주고 이 메서드를 apiInfo의 인자로 호출하여 반환되는 ApiInfo 객체를 인자로 넘겨준다.

bean 객체에서 paths의 경우

.paths(PathSelectors.ant("/cloudvendor/*"))

이렇게 실행했을 때, 왜 get이랑 delete만 document에 뜨는지 모르겠다.

모두 띄우기 위해서 와일드카드로 *를 하나 더 붙여주었다.

(이유는 아직 모르겠음.)

내가 초기에 controller 클래스에서 각 mapping의 경로를 지정할 때 "/"를 붙이는 걸 빼먹어서 포함이 안되었던 것이다.

추가해주니, 위처럼 * 하나만 붙혀도 crud 모두 document 상에서 확인되었다.

실행하고 http://localhost:8080/swagger-ui/ 를 다시 접속하여 커스텀 되었는지 확인해보자.

우리가 ApiInfo에다가 설정해준대로, api document 제목도 Cloud Vendor API Application이라고 뜨며, 이 api가 cloud vendor api임을 더욱 이해할 수 있다.

또한 아래 파란색 글씨로, 나의 이름, wedsite, email 정보들이 있으며, license 정보도 잘 적혀있다.

website, email, license의 경우 누르면 해당 페이지로 이동할 수 있다.

또한 cloud vendor api만 문서화함으로써 아래 basic-error-controller도 제외된 것을 확인할 수 있다.

cloud vendor controller에 대한 모든 crud 메서드가 뜨는 것을 확인할 수 있다.

저안에서 직접 값을 입력하고 검색하며 api의 동작을 확인하고 이해할 수 있다.

api 사용자가 이 swagger ui를 열어서 봤을 때 조금더 명확하게 정보를 이해하도록 할 수는 없을까??

특정 model의 어떤 속성은 무슨 속성을 말하는 걸까? 이런 디테일한 정보를 알려주기 위해서 좀 더 디테일하게 커스텀을 진행해보자. 필수는 아니지만, 이렇게 디테일하게 알려줌으로써 api 사용자에게 확실한 정보를 줄 수 있다.

이를 위해서 각 controller와 model의 속성 각각에 추가 정보를 담아서 document에 반영해보자.

💡 controller & model api doc detail custom

먼저 controller의 get 메서드이다.

@GetMapping("/{vendorId}")
@ApiOperation(value = "cloud vendor id", notes = "Provide cloud vendor details",
response = ResponseEntity.class)

vendorId로 cloudvendor를 검색하기 위한 (읽기 위한) 메서드이다.

이 메서드에 대한 정보를 좀 더 디테일하게 알려주기 위해서 아래에 @ApiOperation이라는 어노테이션을 추가한다.

그리고 이 메서드의 동작에 대한 내용을 인자에 적어주는 것이다.

value = 이 메서드의 입력으로 들어가는 정보 = cloud vendor의 id

notes = 이 메서드가 어떤 역할을 하는지 = 해당 cloud vendor의 정보를 제공한다.

response = 응답 형태 = ResponseEntity 형태로 반환을 한다.

이러한 작은 코드가 api document를 더욱 명확하게 만들어 준다.

다음으로 model인 cloudvendor를 보자.

@Entity
@Table(name = "cloud_vendor_info")
@ApiModel(description = "This table holds cloud vendor information.")

이 entity가 어떤 정보인지에 대한 설명을 추가하고자 한다.

table 아래 @ApiModel 어노테이션을 추가하여 이 entity에 대한 desciption을 추가해줄 수 있다.

또한 entity 내의 각 속성에 대해서도 추가 설명을 적을 수 있다.

@Id
@ApiModelProperty(notes = "This is a Cloud Vendor Id. It shall be unique.")
private String vendorId;

vendorId에 대한 추가 정보를 @ApiModelProperty 어노테이션을 추가함으로써 적을 수 있다.

실행 후, swagger-ui를 확인해보자.

변경된 내용을 보면, get은 cloud vendor id를 입력으로 받으며, 이 메서드는 cloud vendor details을 제공한다는 설명이 있는 것을 확인할 수 있다.

또한 model의 cloudvendor를 보면 description에 추가해준 내용이 반영되어, 이 모델은 cloud vendor의 정보를 담는 table임을 명확하게 전달하고 있다.

또한 그 중 vendorId 속성에 대해서도, cloud vendor id를 나타내며 unique한 특성을 가진다는 정보를 전달하고 있다.

이로써 우리가 커스텀한 대로 api document에 잘 반영되는 것을 확인할 수 있으며, api의 동작이 좀 더 이해하기 쉽고 명확해진 것을 알 수 있다.

이렇게 api 문서를 통해 api 사용자가 이해하기 쉽도록 정보를 전달함으로써 개발 효율을 높힐 수 있다.