[Spring boot] Swagger

 

 

Swagger란?

자바 API 문서 자동화 중 하나입니다.

개발자가 REST API 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 돕는 오픈 소스 소프트웨어 프레임워크입니다.

Swagger에는 자동화된 문서와 코드 생성, 테스트 케이스 생성 지원이 포함됩니다.

 

 

---

 

 

Swagger 사용 이유

개발이 끝나면 추후 유지보수를 위해 API Spec에 대한 문서화 작업이 필요합니다.

이미 개발이 끝난 프로젝트를 유지보수할 경우 API에 대해 더욱 쉽게 이해할 수 있기 때문입니다.

또한, 개발 후 개발자가 API 문서를 작성하기 번거롭기 때문에 나온 프레임워크입니다.

 

 

 

---

 

 

Spring boot에서 Swagger 설정

 

1) dependency 추가

(maven을 사용하였습니다.)

<!-- springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>

<!-- springfox-swager-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>

 

2) Config 생성

'SwaggerConfig.java'를 생성하고 다음과 같이 생성합니다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("유찌")
				.description("유찌 Swagger")
				.build();
	}
	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(this.apiInfo())
				.select()
				.apis(RequestHandlerSelectors.any())
			.paths(PathSelectors.ant("/api/**")).build();
	}
}

* apiInfo()는 없어도 괜찮습니다.

 

3) Swagger UI

Swagger UI

'localhost:[port]/swagger-ui.html'로 접속하여 다음과 같은 화면이 나오는 것을 확인합니다.

 

 

---

 

코드와 Swagger-ui 비교

 

프론트와 백단을 어느 정도 구성한 후의 Swagger UI 모습입니다.

Swagger UI

 

코드와 Swagger UI을 같이 보면..

@Api(tags = "인증권한")
@RestController
public class AuthController {
 
    @ApiOperation(value = "토큰 삭제")
    @GetMapping(value = Path.REMOVE_TOKEN)
    public ResponseEntity<?> removeToken(HttpServletRequest request) throws Exception {
        String authHeader = request.getHeader("Authorization");
        String jwtToken   = authService.getJwtToken(authHeader);
        String memId     = authService.getUserId(jwtToken);

        authService.getLogoutTime(memId);
        
        return ResponseEntity.ok().body(memId + " logout");
    }
}

@Api의 tags와 @ApiOperation의 value의 값이 Swagger UI에 들어가게 됩니다.

 

Swagger UI 사진 속 빨간 상자 안의 'SMS 인증', '공통코드', '인증권한', '회원'은 각 Controller의 @Api 어노테이션 tags 값입니다.

 

또한, 노란 상자 안의 '토큰 발급', '토큰 삭제', '토큰 갱신'이 있는데 이는 '인증권한' Controller 속 각 메소드의 @ApiOperation 어노테이션 value 값입니다.