[Spring Boot] Swagger 3.0 적용

Swagger 란?

• API 명세를 도와주는 도구 (협업을 할 때 유용)
  • API 명세 : 프론트엔드와 백엔드 사이에서 어떤 방식으로 데이터를 주고 받을지에 대해 명세하는 것
• 회원 추가, 조회 예제를 만들어보고, 이 예제에 Swagger 3.0을 적용 시켜봄

회원 추가, 조회 예제

• 여기가 포인트가 아니기 때문에 최대한 간단하게 구현
  • DB도 연결 안하고 최대한 간단하게 구현
• 회원 추가 : 닉네임, 비밀번호를 입력받음
  • ID를 자동으로 추가해 회원가입 진행
• 회원 조회 : ID를 Path Variable로 받아 해당 회원 정보를 출력
• 회원 리스트 : 전체 회원 리스트 출력

User 객체

@Getter
@AllArgsConstructor
public class User {
    private int id;
    private String nickname;
    private String password;
}

UserAddDto

• Request Body로 User을 입력받을 때 사용되는 DTO

@Getter
public class UserAddDto {
    private String nickname;
    private String password;
}

UserController

@RestController
public class UserController {

    private List<User> users = new ArrayList<>();
    private int id = 0;

    // User 추가
    @PostMapping("/user")
    public String add(@RequestBody UserAddDto user) {
        users.add( new User(id, user.getNickname(), user.getPassword()) );
        id ++;
        return "User 추가 완료";
    }

    // User 조회
    @GetMapping("/user/{id}")
    public User findById(@PathVariable int id) {
        return users.get(id);
    }

    // User 전체 조회
    @GetMapping("/users")
    public List<User> findAll() {
        return users;
    }
}

결과

• POST /user : Request Body에 nickname, password를 넣어 전송하면 User가 id를 자동으로 배정받고 추가됨
• GET /user/{id} : Path Variable로 id를 넣고 전송하면 해당 id의 User return
• Get /users : 모든 User 출력

Swagger 3.0 적용

라이브러리 추가

• 필요한 라이브러리
  1. springfox-boot-starter (3.0.0)
  2. springfox-swagger-ui (3.0.0)
• build.gradle에서 라이브러리 추가

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

SwaggerConfig.java 생성 후 아래 코드 입력

@Configuration
@EnableWebMvc
public class SwaggerConfig {

    @Bean
    public Docket swaggerApi() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.study.hellospring.controller"))
                //.apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(mySwaggerInfo());
    }

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

• DocumentationType.OAS_30 : Swagger 3.0 을 뜻함
• select() : ApiSelectorBuilder 생성
• apis() : Swagger을 적용할 API 선택
  • RequestHandlerSelectors.any() : 프로젝트 내의 모든 패키지에 적용
  • RequestHandlerSelectors.basePackage(패키지명) : 특정 패키지 내의 모든 Controller에 적용
• paths() : 위의 apis로 선택된 API 중 paths 내의 조건에 맞는 API 필터링
  • PathSelectors.any() : 모든 API 통과
• build() : 빌드
• apiInfo() : 제목, 설명 등 Swagger API에 대한 정보를 받아와 출력 (Optional)
  • mySwaggerInfo : 임의로 설정한 Swagger에 대한 정보

메소드 별 설명 추가 (Optional)

• Controller의 Method에 Swagger 문서에 나타날 설명을 추가할 수도 있음
• 예시를 위해 아래 어노테이션들을 UserController의 add 메소드에만 추가

@Operation(summary = "Add User", description = "유저 추가")
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "통과"),
        @ApiResponse(responseCode = "400", description = "실패")
})

결과

• http://localhost:8080/swagger-ui/ 에서 확인 가능

Swagger UI에서 테스트 진행

1. 원하는 API 선택 후 Try it out 클릭
   
   
2. Request Body 채워주고 Execute 클릭
   
   
3. User 추가 후 id 값(0) 넣어주고 findById 한 결과
   
   
4. findAll 결과
   
   
5. 위에서 @Operation, @ApiResponses로 설명 추가해준 결과