Overview

프로젝트를 진행하면서 API는 Notion에서 관리했다.
그 과정에서 팀원중에 실수로 수정하거나 삭제하는 경우가 발생해서 난감했던 상황도 있었다. 우리는 프로젝트 막바지에 Swagger를 알게되었고 배포가 끝난 상황에서 적용해봤다. 처음엔 UI가 보기 좋다, 갈끔하게 정리되는구나? 정도만 보고 넘어갔다.
개인적으로 연습겸 프로젝트를 하나 하고있는데, Swagger를 적용해서 진행 해보라는 동료의 조언에 전에 진행했던 프로젝트에서는 크게 느낌이 없었는데..? 라고 생각했다.
Swagger관련하여 이것저것 찾아봤고 적용해봤다. 내가 아직 Swagger를 완벽히 활용하고 있지 않지만 놀라웠다...
단순 문서화 하는게 아닌 API를 문서내에서 Parameter를 넣어가며 바로바로 실행이 가능했다. 별도 테스트 페이지를 제작하거나 postman으로 실행하지 않고도 Swagger문서에서 가능했다. 크게 복잡하지 않은 시스템이라면 Swagger 적용 후 API를 호출하는 작업자에게 설명하고 문서 만들 것도 없이 Swagger url만 전달해주면 작업할 수 있다.
굉장히 편리하다고 느꼈다. Swagger와 적용하는 방법을 알아보자

1. Swagger란?

Swagger는 OAS(Open Api Specification)를 위한 프레임워크다.
개발자들이 API문서화를 쉽게 할 수 있도록 도와주며 parameter를 넣어서 실제로 어떤 응답이 오는지 테스트도 가능하다.
또한 협업하는 클라이언트 개발자들에게 Swagger만 전달해주면 API Path와 Request, Response값 및 제약 등을 한번에 알려줄 수 있기에 협업하는데 효율성이 증가한다.

2. Swagger 적용

Swagger 2.x 버전, 3.x 버전 모두 적용 가능하다.
큰 차이가 없어 나는 최신 버전인 Swagger 3.x 버전을 적용했다.

2-1. 의존성 추가

• Gradle 추가

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

2-2. 설정 클래스

• @Configuration 어노테이션 사용
• '.basePackage()' 부분에 Swagger를 적용할 패키지를 지정해준다.
  -> 해당 패키지 이하의 모든 rest api가 자동으로 swagger 문서로 생성된다.

@Configuration
@EnableWebMvc
public class SwaggerConfig {

    private ApiInfo swaggerInfo() {
        return new ApiInfoBuilder().title("Board API")
                .description("Board API Docs").build();
    }

    @Bean
    public Docket swaggerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .consumes(getConsumeContentTypes())
                .produces(getProduceContentTypes())
                .apiInfo(swaggerInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.example.board.controller"))
                .paths(PathSelectors.any())
                .build()
                .useDefaultResponseMessages(false);
    }

    private Set<String> getConsumeContentTypes() {
        Set<String> consumes = new HashSet<>();
        consumes.add("application/json;charset=UTF-8");
        consumes.add("application/x-www-form-urlencoded");
        return consumes;
    }

    private Set<String> getProduceContentTypes() {
        Set<String> produces = new HashSet<>();
        produces.add("application/json;charset=UTF-8");
        return produces;
    }

}

만약 해당 패키지 내에 포함되지만 Swagger 문서로 만들고 싶지 않을 겨우 해당 Controller에 @ApiIgnore 어노테이션을 추가하면 제외 가능하다.

@ApiIgnore
@RequiredArgsConstructor
@RestController
public class UserController {

2-3. API별 설명 작성

@RequiredArgsConstructor
@RestController
public class UserController {

    private final UserService userService;

    //회원가입
    @ApiOperation(value="회원가입 동작여부 확인", notes="회원가입 정상 동작 시 'true' return ")
    @ApiResponses({
            @ApiResponse(code = 200, message = "API 정상 작동"),
            @ApiResponse(code = 500, message = "서버 에러")
    })
    @PostMapping("/post/user/signup")
    

2-4. Parameter 설명

public class UserRegisterRequestDto {

    @ApiModelProperty(value = "회원 아이디", dataType = "string", required = true)
    private String username;
    @ApiModelProperty(value = "비밀번호" ,dataType = "string", required = true)
    private String password;
    @ApiModelProperty(value = "비밀번호 확인", dataType = "string", required = true)
    private String passwordCheck;

}

@ApiModelProperty: 속성의 내용, 데이터 타입, 예문, 필수여부 등을 설정

2-5. 실행 후 접속

로컬 실행 후 Swagger URL로 접속하면 된다.
(3.x 버전)
http://localhost:8080/swagger-ui/

**참고
https://github.com/springfox/springfox
https://milenote.tistory.com/67
https://bcp0109.tistory.com/326
https://velog.io/@kero1004/springboot-Swagger