API 문서 만들기 - OpenAPI 3.0 적용하기

OpenAPI 란?

OpenAPI Specification 3.0 ( OAS ) 라고도 하며  이전 2.0버전까지는 Swagger 라는 도구로 더 유명하다.

아직까지도 Swagger (스웨거) 3 라거나 하는 경우도 종종 있는거같다.

OpenAPI 는 RESTFul API를 명세화하거나 문서화 하기 위한 도구로 개발되었으며, 최소한의 구현으로 한눈에 API에 필요한 내용을 파악하기 위해 만들어지고 사용되고 있다. 즉, API를 문서화하기 위한 도구 라고 이해하는 것이 맞다.

그렇다면 왜 이런 도구가 필요해진걸까? 조금만 생각해보자면 현업에서 다양한 사람들과, 여러 클라이언트들에게 

내가 혹은 우리회사가 만든 api 를 제공하거나 개발해야하는 경우가 많다. 이때, 이 api를 한눈에 보여주고 필요한 사항을 요구하려면 문서화 할 수 밖에 없을것이다. 일일히 설명하는 것은 비효율 적이고. 이때 문서화 하기 위한 도구로 많은 선택지가 있다.

엑셀 스프레드시트, PDF, 파워포인트 등등 .. 이런 기본적인 사무용 툴을 사용하여 작성하면 되겠지만 많은 수고와 개발자에게 

불필요한 단순작업일 가능성이 높다. 그래서 OpenAPI 같은 도구들이 등장했다.

특히 OpenAPI 는 측에서 밀어주는 SpringDoc 에 내장?되어 있는 툴이다. 

 

SpringBoot 추가 

Dependency 먼저 추가해보자. 작성일 기준 2022.08.31 최신버전은 1.6.11 이다.

// Maven
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.11</version>
</dependency>

// Gradle
implementation 'org.springdoc:springdoc-openapi-ui:1.6.11'

 

 

설정

기본적인 설정은 먼저 application.property 혹은 yml 파일을 통해 정한다. 나는 yml 을 기준으로 작성했다. 

자세한 내용은 여기

springdoc:
    version: '@project.version@'
    api-docs:
      path: /api-docs #접속 Path 설정
    paths-to-match: /v1/api #매핑주소로 해당 주소만 문서화하도록 지정할 수 있다.
    default-consumes-media-type: application/json #request content-type 설정
    default-produces-media-type: application/json #response content-type 설정
    swagger-ui:
      path: /swagger-ui #접속 Path 설정
      display-request-duration: true # ui 에서 try it out 했을 때 적용

기본설정

WebConfig 처럼 OpenAPIConfig class 를 생성한다.

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI openAPI(@Value("${springdoc.version}") String version) {
        Info info = new Info()
                .title("API 문서의 제목")
                .version(version)
                .description("subTitle을 적어주세요.");
        return new OpenAPI().components(new Components()).info(info);
    }
}

이외에도 info 안에 많은 method 들이 있다. contact 를 통해 작성자의 연락처나 메일등을 남기거나 하는 용도로 사용할 수 있다.

 

구현

API 는 보통 Controller 단에서 request를 받고 response 를 반환한다.

그러므로 Controller를 기준으로 작성해보자. 

 

@Tag( name = "" ) 으로 해당 컨트롤러의 제목을 정하고 description 으로 자세한 명세나 설명을 넣는다.

@Operation(description = "") 으로 해당 메서드의 HTTP 명세를 정의할 수 있다.

 

@Tag(name = "제목 : 유저의 정보를 관리하기 위한 컨트롤러", description = "부재 : 혹은 세부사항")
@RequiredArgsConstructor
@RequestMapping("/user")
@RestController
@Slf4j
public class UserController {

    private final UserService userService;
	
    @Operation(description = "회원가입")
    @PostMapping("/signup")
    public Object signup(@RequestBody @Valid UserDTO userDTO, BindingResult bindingResult
    ) throws Exception {
       

        if(!userDTO.getPassword1().equals(userDTO.getPassword2())) {
            bindingResult.rejectValue("password2", "passWordInCorrect",
                    "비밀번호가 일치하지 않습니다!");
            return  bindingResult.getFieldError().getDefaultMessage();
        }


        UserEntity userEntity = userService.createUser(userDTO);

        return userEntity;
    }

 

스키마 사용하기 

dto 혹은 vo 같은 객체를 빈으로 사용할 때 Schema 를 통해 해당 변수가 어떤 필요 파라미터인지 정의할 수 있다.

public class User {

    @Schema(description = "유저의 계정", defaultValue = "기본값을 설정가능")
	private String uid;
    
    ...
}

 

이런식으로 간단히 세팅을 통해 문서화를 차근차근 진행한다면 나중에 수정사항등으로 코드가 바뀌거나 요구사항이 변경되어도 

간편히 api 문서도 수정이 가능하게 된다.

 

그리고 위에 property 에서 설정한 경로로 접속하거나, default 경로인 http://localhost:8080/swagger-ui 를 접속하면 OpenAPI의 

swagger-ui를 볼 수 있다!

 

http://localhost:8080/swagger-ui

 

이렇게 작성된 문서를 브라우저를 통해 보거나, 파일 -> 인쇄 -> PDF로 출력 하기,

혹은 서버에 띄었다면 서버도메인등을 통해 들여다볼수도 있다! 

이젠 쉽게 다른 api들도 코딩하고 문서를 통해 확인해보면 편하겠다!