Portfolio

🔎 들어가기전에

Open API와 OpenAPI

Open API : 개방된 API로 누구나 사용될 수 있도록 API의 endpoint가 개방 되어있다. ex) 우체국의 우편번호 API

OpenAPI : OpenAPI Specification(OAS) 라고 부르는데 이는 REST API를 정의된 규칙에 맞게 API 스펙을 json이나 yaml로 표현하는 방식 => 즉, REST API 디자인에 대한 정의(Specification) 표준

Swagger와 OpenAPI

예전에는 Swagger 이름으로 불렸다가 2015년에 전환되어 OpenAPI 3.0 Specification으로 칭합니다.

OpenAPI = 사양, REST API 디자인에 대한 정의

Swagger = 사양 구현을 위한 도구 => API들이 갖고있는 specification을 정의할 수 있는 tool 중 하나

Swagger와 OpenAPI의 차이

OpenAPI란 ?

🍉 Springfox-swagger vs springdoc-openapi

공통점

Swagger를 사용하고 API 문서를 쉽게 쓸 수 있도록 해준다.
스프링 프레임워크를 사용하는 프로젝트에서 사용가능한 라이브러리

Springfox

2018년까지 많은 사람들이 사용하다가 2018년 6월 업데이트가 중지되었다가 2020년 6월 새로운 버전을 출시하였다.

SpringDoc

2019년 7월 출시되어 업데이트가 없어진 springfox 대신에 사람들이 많이 사용하기 시작했다.
webflux non-blocking 비동기 방식의 웹 개발 지원한다.

⛄️ 우리는 spring doc을 사용합니다.

🦁 Setting

1. build.gradle dependency 추가


 implementation 'org.springdoc:springdoc-openapi-ui:1.6.9'
 implementation 'org.springdoc:springdoc-openapi-security:1.6.9'

2. security config 설정


@Configuration
 @Profile({"dev", "local", "mem"})
 public class SwaggerConfig {
     @Bean
     public OpenApiCustomiser customOpenApi() {
         return openApi -> {
             String bearer = "bearer";
             openApi
                 .info(new Info().title("instakyuram"))
                 .components(
                     openApi.getComponents().addSecuritySchemes(
                         bearer,
                         new SecurityScheme()
                             .type(SecurityScheme.Type.HTTP)
                             .scheme(bearer)
                             .bearerFormat("JWT")
                             .in(SecurityScheme.In.HEADER)
                             .name("Authorization")
                     )
                 )
                 .addSecurityItem(
                     new SecurityRequirement()
                         .addList(bearer, Arrays.asList("read", "write"))
                 );
         };
     }
 }

spring fox와 달리 다른 config 설정을 해주지 않아도 됩니다.

기존의 yml 파일에 설정했던 저희 팀 swagger의 정보입니다. 이 부분은 위 코드의 .info(new Info().title("instakyuram)) 에 추가할 수 있습니다.

🫒 기존 코드와 변경된 부분 비교 해보기

기존의 코드(Spring fox)


@Api(tags= "팔로우, 팔로잉 api")
@RestController
@RequestMapping("/api/friendships")
public class FollowRestController {
	private final FollowService followService;
	public FollowRestController(FollowService followService) {
		this.followService = followService;
	}

	@Operation(
		summary = "팔로우 가능 여부 판단",
		description = "팔로우 할 수 있는 대상인지 확인합니다.",
		responses = {
			@io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "팔로우 가능 여부 true/false"),
		}
	)
	@GetMapping("/{memberId}")
	public ApiResponse<Boolean> isFollowed(@AuthenticationPrincipal JwtAuthentication auth,
		@PathVariable Long memberId) {
	public ApiResponse<Boolean> isFollowed(
		@AuthenticationPrincipal JwtAuthentication auth,
		@Parameter(
			name = "팔로우 할 대상의 식별 값", description = "사용자 id 값(숫자)을 입력합니다.", in = ParameterIn.PATH, required = true
		) @PathVariable Long memberId) {
		return new ApiResponse<>(followService.isFollowed(auth.id(), memberId));
	}

spring doc 사용


@Tag(name = "팔로우, 팔로잉 api")
@RestController
@RequestMapping("/api/friendships")
public class FollowRestController {

	private final FollowService followService;

	public FollowRestController(FollowService followService) {
		this.followService = followService;
	}

	@Operation(summary = "팔로우 가능 여부 판단", description = "팔로우 할 수 있는 대상인지 확인합니다.")
	@GetMapping("/{memberId}")
	public ApiResponse<Boolean> isFollowed(
		@AuthenticationPrincipal JwtAuthentication auth,
		@PathVariable Long memberId) {
		return new ApiResponse<>(followService.isFollowed(auth.id(), memberId));
	}