Swagger

✅ Swagger

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

✅ 사용 방법

✔️ Spring Boot 3.0 이하 버전

• Spring Boot에서는 build.gradle에서 dependencies에 springfox-boot-starter 를 추가하여 사용
  • implementation 'io.springfox:springfox-boot-starter:3.0.0'
• localhost:8080/swagger-ui/ 로 Swagger 페이지에 접근할 수 있다.

✔️ Spring Boot 3.0 이상 버전

• ❗Spring Boot 3.x 이상 부터는 springfox가 아닌 springdoc을 사용해야 한다.
  • implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
• localhost:8080/swagger-ui/index.html로 Swagger 페이지에 접근할 수 있다.

✅ Annotations (swagger 2(springfox) -> swagger 3(springdoc))

• @Api → @Tag
• @ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
• @ApiImplicitParam → @Parameter
• @ApiImplicitParams → @Parameters
• @ApiModel → @Schema
• @ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
• @ApiModelProperty → @Schema
• @ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
• @ApiParam → @Parameter
• @ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

✅ 사용 예시

아래 예시의 어노테이션들이 해당 범위(클래스, 메소드 등)에 제한되어 사용되는 것은 아님

Config

• 명세 전체에 대한 공통 설명을 설정하기 위한 설정 파일

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI openAPI(@Value("${springdoc.version}") String springDocVersion) {
        Info info = new Info()
                .title("Swagger 테스트 API")
                .version(springDocVersion)
                .description("Swagger 사용 방법에 대한 테스트 입니다.")
                .contact(new Contact().name("chris").email("chris@gmail.com").url("https://myWebsite.com"));

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

Controller

• @Tag(name = "", description = "")

@Tag(name = "API Controller", description = "API 정보를 제공하는 Controller")
@RestController
@RequestMapping("/api")
public class SwaggerController {
	...
}

Method

• @Operation
• @ApiResponses
• @Parameter

@GetMapping("/plus/{x}")
    @Operation(operationId = "plus", summary = "더하기 메소드", description = "더하기 메소드 입니다.")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Successful Operation", content = @Content(schema = @Schema(implementation = int.class))),
            @ApiResponse(responseCode = "400", description = "Bad Request", content = @Content(schema = @Schema(implementation = int.class)))
    })
    public int plus(@PathVariable @Parameter(name = "x", description = "x 값", in = ParameterIn.PATH, example = "10") int x,
                    @RequestParam @Parameter(name = "y", description = "y 값", in = ParameterIn.QUERY, example = "20") int y) {
        return x + y;
    }

DTO

• @Schema

@Data
public class UserRequest {

    @Schema(description = "이름", defaultValue = "testId", requiredMode = Schema.RequiredMode.REQUIRED, example = "steve")
    private String name;
    
    @Schema(description = "나이", defaultValue = "1", requiredMode = Schema.RequiredMode.REQUIRED, example = "30")
    private int age;
}

✅ Swagger 사용 시 주의점

• 운영 환경과 같은 외부에 노출되면 안되는 환경에서 사용할 때는 주의해야 한다.

참고 Reference

• https://springdoc.org
• https://springdoc.org/v2/
• https://wildeveloperetrain.tistory.com/156