[Swagger] Swagger란?

Swagger란?

Swagger란 개발한 Rest API를 편리하게 문서화해주고, 이를 통해서 관리 및 제3의 사용자가 편리하게 API를 호출해 보고 테스트할 수 있는 프로젝트이다.

Spring boot에서 Swagger를 사용하면, 컨트롤러에 명시된 어노테이션을 해석하여 API문서를 자동으로 만들어준다.

 

---

Swagger Annotation

 

---

사용 예시

build.gradle

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'

 

SwaggerConfig

@Configuration
@OpenAPIDefinition
public class SwaggerConfig {

    /**
     * 명세서 정보
     */
    @Bean
    public OpenAPI api(){
        Info info = new Info().title("RESTful API 명세서").version("v3.2.1")
                .description("Spring Boot로 개발하는 RESTful API 명세서 입니다.");

        return new OpenAPI().components(new Components()).info(info);
    }

    /**
     * 경로 그룹화
     */
    @Bean
    public GroupedOpenApi customOpenAPI() {
        String[] paths = {"/api/user/**"};

        return GroupedOpenApi
                .builder()
                .group("읽기 허용된 API")
                .pathsToMatch(paths).build();
    }

}

 

User

@Data
@AllArgsConstructor
@Schema(description = "사용자 상세 정보를 위한 도메인 객체")
public class User {
    @Schema(title = "사용자 ID", description = "사용자 ID는 자동 생성됩니다.")
    private Long id;

    @Schema(title = "사용자 이름", description = "사용자 이름을 입력합니다.")
    private String name;

    @Schema(title = "사용자 나이", description = "사용자 나이를 입력합니다.")
    private Integer age;

}

 

UserController

@Tag(name = "user-controller", description = "일반 사용자 서비스를 위한 컨트롤러입니다.")
@RestController
@RequestMapping("/api/user")
public class UserController {

    @PostMapping
    public ResponseEntity<User> createUser(@RequestBody User user) {
        return ResponseEntity.ok(user);
    }

    @Operation(summary = "사용자 정보 조회 API", description = "사용자 ID를 이용해서 사용자 상세 정보 조회를 합니다.")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "OK!!"),
            @ApiResponse(responseCode = "400", description = "BAD REQUEST!!"),
            @ApiResponse(responseCode = "404", description = "USER NOT FOUND!!"),
            @ApiResponse(responseCode = "500", description = "INTERNAL SERVER ERROR!!"),
    })
    @GetMapping("/{id}")
    public ResponseEntity<User> findUser(
            @Parameter(description = "사용자 ID", required = true, example = "1") @PathVariable Long id) {
        return ResponseEntity.ok(new User(id, "김형민", 25));
    }
}

 

http://localhost:8080/swagger-ui/index.html