[SpringBoot] Spring Docs + Swagger 적용하여 API 문서 자동화하기

API 문서화는 개발자들 간의 원활한 협업을 위한 필수 요소입니다. 명확한 문서가 없다면 API 사용법을 제대로 전달하기 어려워지고, 그로 인해 개발 과정에서 혼란이나 유지보수에 어려움을 겪을 수 있습니다.

특히, API의 변경 사항이 있을 때마다 문서도 수동으로 업데이트 해야 한다면, 번거롭고 오류가 발생할 위험 또한 증가하게 됩니다. 이런 문제를 Swagger를 통해 해결할 수 있습니다.

이번 포스팅에서는 Swagger란 무엇인지, 적용하는 방법, 사용되는 어노테이션에 대해 알아보겠습니다.

Swagger란?

Swagger는 웹 서비스 명세를 문서화 해주는 OpenAPI기반의 프레임워크로, 웹 서비스의 로직 수행, 요청 데이터, 응답 데이터가 무엇인지 정리해서 문서화를 자동화 해주는 기술입니다.

웹 애플리케이션 개발에서는 보통 Frontend와 Backend가 나뉘어 개발을 진행하게 되는데, 이때 Backend 팀이 만든 서비스를 Swagger로 문서화하여 Frontend 팀에게 전달함으로써 로직의 이해도를 높이고 원활한 소통을 도와줍니다.

Swagger를 사용하면, 개발과정에서 계속해서 변경되는 API 문서가 자동으로 업데이트되기 때문에, 수동으로 문서를 수정하는 번거로움을 없애고 개발 외의 시간을 절약할 수 있습니다.

Swagger 종류

Spring에는 SpringFox와 SpringDoc 두 가지 방식의 Swagger가 존재합니다. 과거에는 SpringFox를 주로 사용하였으나, 2020.07.14 일자를 기준으로 더 이상 업데이트가 이루어지지 않으면서 현재는 SpringDoc이 더 많이 사용되고 있습니다.

SpringDoc은 OpenAPI 3.0을 지원하며, 최신 버전의 Spring과의 호환성도 좋기 때문에, 현재는 대부분의 프로젝트에서 SpringDoc을 선호하고 있습니다.

Swagger 적용하기

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

먼저 SpringDoc Swagger를 사용하기 위해 의존성을 추가합니다. 버전 확인

Swagger 의존성 추가 후 default 주소로 접속 시 해당 화면이 나타나게 됩니다.

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

Swagger Config 설정

 @Configuration
public class SwaggerConfig {
 
    @Bean
    public OpenAPI openAPI() {
        Server devServer = new Server();
        devServer.setUrl("/"); // API 서버 설정
 
        Server prodServer = new Server();
        prodServer.setUrl("운영 URL"); // 운영서버에 따로 띄우기 위한 서버 추가 가능
 
        Info info = new Info()
                .title("Swagger API") // API 문서 제목
                .version("1.0.0") // API 문서 버전
                .description("Swagger API Description"); // API 문서 설명
 
        return new OpenAPI()
                .info(info)
                .servers(List.of(devServer, prodServer));
    }
}

Swagger Config 설정을 통해 API 문서의 서버 설정, 제목, 버전, 설명을 추가하고 난 뒤의 이미지입니다. 사용자는 개발 서버와 운영 서버 중 하나를 선택하여 해당 서버의 API 엔드포인트를 테스트할 수 있습니다.

API 문서화

이제 백엔드 서버에서 API를 생성할 때, Swagger를 활용하여 자동으로 API 문서화가 이루어지는 모습을 확인할 수 있습니다.

Swagger는 RequestMapping 경로와 HTTP 메서드(GET, POST 등)에 따라 API 문서를 자동으로 생성합니다.

 @RestController
@RequestMapping("/api/swagger")
public class SwaggerController {
 
    @GetMapping
    public String getSwagger() {
        return "swagger example";
    }
 
    @PostMapping
    public String postSwagger(@RequestBody SwaggerRequest swaggerRequest) {
        return "swagger example";
    }
}

SwaggerController 클래스는 /api/swagger 경로로 들어오는 GET, POST 요청을 처리하는 예시코드입니다.

 @Getter
public class SwaggerRequest {
 
    private String name;
    private String gender;
    private int age;
}

SwaggerRequest 클래스는 RequestBody 값을 표현하기 위한 예시 클래스 입니다.

Swagger는 어노테이션(@GetMapping, @PostMapping 등)을 기반으로 API의 경로와 메서드를 자동으로 인식하여, Swagger UI에서 위의 이미지 처럼 각 API의 경로, HTTP 메서드, 요청 파라미터, 응답 등이 자동으로 문서화되어 나타나게 됩니다.

API 문서화 세부 설정

Swagger를 통해 기본적인 API 문서화가 이루어지면, 실제 프로젝트에서 Swagger를 더 유용하게 활용하기 위해 세부 설정을 할 수 있습니다.

기본적인 문서화 외에도 다양한 설정을 제공하여 API 문서에 대한 추가 정보나 규격을 정의할 수 있습니다. 예를 들어 API의 요청, 응답에 대한 설명 추가, 특정 API의 보안 설정을 지정하는 등의 세부 설정을 통해 문서를 더욱 명확하게 만들 수 있습니다.

@Tag

@Tag(name = "Swagger", description = "Swagger API")

 @Tag(name = "Swagger", description = "Swagger API")
@RestController
@RequestMapping("/api/swagger")
public class SwaggerController {
 
    @GetMapping
    public String getSwagger() {
        return "swagger example";
    }
 
    @PostMapping
    public String postSwagger(@RequestBody SwaggerRequest swaggerRequest) {
        return "swagger example";
    }
}

@Tag 어노테이션은 Controller에 적용하여 해당 컨트롤러의 이름과 설명을 추가할 수 있습니다.

@Operation

@Operation(summary = "Swagger 게시물 조회", description = "등록 된 Swagger 게시물을 조회합니다.")

 @Tag(name = "Swagger", description = "스웨거 API")
@RestController
@RequestMapping("/api/swagger")
public class SwaggerController {
 
    @Operation(summary = "Swagger 게시물 조회", description = "등록 된 Swagger 게시물을 조회합니다.")
    @GetMapping
    public String getSwagger() {
        return "swagger example";
    }
 
    @PostMapping
    public String postSwagger(@RequestBody SwaggerRequest swaggerRequest) {
        return "swagger example";
    }
}

@Operation 어노테이션은 API 엔드 포인트를 정의하며, 해당 메서드의 간단한 설명과 세부 설명을 추가합니다.

@ApiResponse

 @ApiResponses({
        @ApiResponse(responseCode = "200", description = "응답 성공"),
        @ApiResponse(responseCode = "400", description = "잘못된 요청")
})

 @Tag(name = "Swagger", description = "스웨거 API")
@RestController
@RequestMapping("/api/swagger")
public class SwaggerController {
 
    @Operation(summary = "Swagger 게시물 조회", description = "등록 된 Swagger 게시물을 조회합니다.")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "응답 성공"),
            @ApiResponse(responseCode = "400", description = "잘못된 요청")
    })
    @GetMapping
    public String getSwagger() {
        return "swagger example";
    }
 
    @PostMapping
    public String postSwagger(@RequestBody SwaggerRequest swaggerRequest) {
        return "swagger example";
    }
}

@ApiResponses 어노테이션은 API 응답에 대한 설명과 상태 코드를 메서드에 적용하여 정의합니다.

@Content

 @ApiResponse(
        responseCode = "200",
        description = "응답 성공",
        content = @Content(mediaType = "application/json", schema = @Schema(implementation = SwaggerRequest.class))
)

 @Tag(name = "Swagger", description = "스웨거 API")
@RestController
@RequestMapping("/api/swagger")
public class SwaggerController {
 
    @Operation(summary = "Swagger 게시물 조회", description = "등록 된 Swagger 게시물을 조회합니다.")
    @ApiResponses({
            @ApiResponse(
                    responseCode = "200",
                    description = "응답 성공",
                    content = @Content(mediaType = "application/json", schema = @Schema(implementation = SwaggerRequest.class))
            ),
            @ApiResponse(responseCode = "400", description = "잘못된 요청"),
    })
    @GetMapping("/{id}")
    public String getSwagger(
            @Parameter(name = "id", description = "사용자 ID", required = true, example = "1")
            @PathVariable Long id
    ) {
        return "swagger example " + id;
    }
 
    @PostMapping
    public String postSwagger(@RequestBody(description = "Swagger Post 요청 정보") SwaggerRequest swaggerRequest) {
        return "swagger example";
    }
}

@Content 어노테이션은 메서드 응답 본문의 데이터 타입과 스키마를 정의합니다.

@Parameter

@Parameter(name = "id", description = "사용자 ID", required = true, example = "1")

 @Tag(name = "Swagger", description = "스웨거 API")
@RestController
@RequestMapping("/api/swagger")
public class SwaggerController {
 
    @Operation(summary = "Swagger 게시물 조회", description = "등록 된 Swagger 게시물을 조회합니다.")
    @ApiResponses({
            @ApiResponse(
                    responseCode = "200",
                    description = "응답 성공",
                    content = @Content(mediaType = "application/json", schema = @Schema(implementation = SwaggerRequest.class))
            ),
            @ApiResponse(responseCode = "400", description = "잘못된 요청"),
    })
    @GetMapping("/{id}")
    public String getSwagger(
            @Parameter(name = "id", description = "사용자 ID", required = true, example = "1")
            @PathVariable Long id
    ) {
        return "swagger example " + id;
    }
 
    @PostMapping
    public String postSwagger(@RequestBody SwaggerRequest swaggerRequest) {
        return "swagger example";
    }
}

@Parameter 어노테이션은 API 메서드 요청 파라미터의 이름, 설명, 필수 여부 등을 정의합니다.

@RequestBody

@RequestBody(description = "Swagger Post 요청 정보") SwaggerRequest swaggerRequest

 @Tag(name = "Swagger", description = "스웨거 API")
@RestController
@RequestMapping("/api/swagger")
public class SwaggerController {
 
    @Operation(summary = "Swagger 게시물 조회", description = "등록 된 Swagger 게시물을 조회합니다.")
    @ApiResponses({
            @ApiResponse(
                    responseCode = "200",
                    description = "응답 성공",
                    content = @Content(mediaType = "application/json", schema = @Schema(implementation = SwaggerRequest.class))
            ),
            @ApiResponse(responseCode = "400", description = "잘못된 요청"),
    })
    @GetMapping("/{id}")
    public String getSwagger(
            @Parameter(name = "id", description = "사용자 ID", required = true, example = "1")
            @PathVariable Long id
    ) {
        return "swagger example " + id;
    }
 
    @PostMapping
    public String postSwagger(@RequestBody(description = "Swagger Post 요청 정보") SwaggerRequest swaggerRequest) {
        return "swagger example";
    }
}

@RequestBody 어노테이션은 요청 본문 데이터의 상세 정보를 적용합니다.

io.swagger.v3.oas.annotations.parameters.RequestBody를 import합니다.

@Schema

 @Getter
public class SwaggerRequest {
 
    @Schema(name = "이름", description = "회원 이름", example = "tao")
    private String name;
    private String gender;
    @Schema(description = "회원 나이", example = "20", nullable = true)
    private int age;
}

@Schema 어노테이션은 API 모델에 적용하여 모델의 속성을 정의합니다.

@Hidden

 @RestController
@RequestMapping("/api/test")
public class TestController {
 
    @Hidden
    @GetMapping
    public String test() {
        return "test";
    }
}

@Hidden 어노테이션은 적용된 메서드에 대해 숨김을 적용합니다.

앞서 생성한 TestController의 메서드에 @Hidden을 적용하여 사라진 모습을 볼 수 있습니다.

@SecurityScheme

 @SecurityScheme(
        name = "Bearer Authentication",
        type = SecuritySchemeType.HTTP,
        scheme = "bearer",
        bearerFormat = "JWT"
)
@Configuration
public class SwaggerConfig {
 
    @Bean
    public OpenAPI openAPI() {
        Server devServer = new Server();
        devServer.setUrl("/");
 
        Server prodServer = new Server();
        prodServer.setUrl("운영 URL");
 
        Info info = new Info()
                .title("Swagger API")
                .version("1.0.0")
                .description("Swagger API Description");
 
        return new OpenAPI()
                .info(info)
                .servers(List.of(devServer, prodServer));
    }
}

@SecurityScheme 어노테이션은 Swagger에서 API 인증 방식을 정의합니다. SpringBoot + Swagger 사용 시 JWT, OAuth2.0, Session 등 다양한 인증 방식을 설정할 수 있습니다.

@SecurityScheme 설정 후 우측 상단에 Authorize 버튼이 생성되고 로그인 시 응답되는 토큰, 세션 키 등을 입력하면 API를 인증된 상태로 테스트할 수 있습니다.

@SecurityRequirement

@SecurityRequirement(name = "SecurityScheme 이름", scopes = "권한 범위")

 @Tag(name = "Swagger", description = "스웨거 API")
@RestController
@RequestMapping("/api/swagger")
public class SwaggerController {
 
    @Operation(summary = "Swagger 게시물 조회", description = "등록 된 Swagger 게시물을 조회합니다.")
    @ApiResponses({
            @ApiResponse(
                    responseCode = "200",
                    description = "응답 성공",
                    content = @Content(mediaType = "application/json", schema = @Schema(implementation = SwaggerRequest.class))
            ),
            @ApiResponse(responseCode = "400", description = "잘못된 요청"),
    })
    @GetMapping("/{id}")
    public String getSwagger(
            @Parameter(name = "id", description = "사용자 ID", required = true, example = "1")
            @PathVariable Long id
    ) {
        return "swagger example " + id;
    }
 
    @SecurityRequirement(name = "SecurityScheme 이름", scopes = "권한 범위")
    @PostMapping
    public String postSwagger(@RequestBody(description = "Swagger Post 요청 정보") SwaggerRequest swaggerRequest) {
        return "swagger example";
    }
}

@SecurityRequirement 어노테이션은 Swagger에서 API의 보안 인증이 필요한 엔드포인트를 정의할 때 사용됩니다. 즉, 특정 API 엔드포인트에서 JWT 토큰, OAuth2.0, Session 등 인증이 필요함을 명시할 때 활용됩니다.

name 보안 스키마(SecurityScheme)의 이름을 지정합니다. @SecurityScheme 또는 Swagger 설정에서 정의한 보안 스키마의 이름과 일치해야 합니다.
scopes OAuth2.0 인증에서 사용할 권한 범위(OAutm2.0 스코프)를 지정합니다. JWT, Session 인증 사용 시, 이 속성이 무시될 수 있습니다.

마무리

Swagger는 API 문서화를 자동화하고, 개발자들 간의 원활한 협업을 돕는 도구입니다. 특히 Spring 기반의 프로젝트에서는 SpringDoc을 활용하여 OpenAPI 3.0을 손쉽게 적용하고, API 문서를 자동으로 생성하여 개발외의 작업에 대한 번거로움을 크게 줄일 수 있습니다. API 문서가 지속적으로 최신 상태로 유지되어 개발자들은 더욱 효율적으로 작업할 수 있으며, 사용자에게도 직관적인 API 사용법을 제공할 수 있습니다.

그리고 다양한 어노테이션을 통해 API의 세부적인 정보를 상세하게 정의하고, 인증 방식까지 설정할 수 있어 보안성 있는 API 서비스를 제공할 수 있습니다.

소스 코드

https://github.com/o-tao/swagger-example

GitHub - o-tao/swagger-example: SpringDoc을 통한 Swagger 적용

SpringDoc을 통한 Swagger 적용. Contribute to o-tao/swagger-example development by creating an account on GitHub.

github.com

'Spring' 카테고리의 다른 글

[SpringBoot] Scale-out 환경에서 발생하는 Scheduler 중복 실행 문제 Shedlock으로 해결하기 (0)	2025.02.06
[SpringBoot] 트랜잭션 전파 속성 (Transaction propagation) (0)	2025.02.02
[SpringBoot] AWS S3 다중 이미지 파일 업로드 및 삭제 구현하기 (feat. MultipartFile) (2)	2025.01.17
[SpringBoot] @Scheduled를 이용한 스케줄러 구현 (0)	2025.01.13
[SpringBoot] AWS SES로 이메일 전송 기능 구현하기 (0)	2025.01.12

내 블로그 - 관리자 홈 전환	`Q` `Q`
새 글 쓰기	`W` `W`

글 수정 (권한 있는 경우)	`E` `E`
댓글 영역으로 이동	`C` `C`

이 페이지의 URL 복사	`S` `S`
맨 위로 이동	`T` `T`
티스토리 홈 이동	`H` `H`
단축키 안내	`Shift` + `/` `⇧` + `/`

[SpringBoot] Spring Docs + Swagger 적용하여 API 문서 자동화하기

Swagger란?

Swagger 종류

Swagger 적용하기

Swagger Config 설정

API 문서화

API 문서화 세부 설정

@Tag

@Operation

@ApiResponse

@Content

@Parameter

@RequestBody

@Schema

@Hidden

@SecurityScheme

@SecurityRequirement

마무리

소스 코드

'Spring' 카테고리의 다른 글

댓글

이 글 공유하기

티스토리툴바

개인정보

단축키

내 블로그

블로그 게시글

모든 영역

Swagger란?

Swagger 종류

Swagger 적용하기

Swagger Config 설정

API 문서화

API 문서화 세부 설정

@Tag

@Operation

@ApiResponse

@Content

@Parameter

@RequestBody

@Schema

@Hidden

@SecurityScheme

@SecurityRequirement

마무리

소스 코드

'Spring' 카테고리의 다른 글

댓글

이 글 공유하기

다른 글

[SpringBoot] Scale-out 환경에서 발생하는 Scheduler 중복 실행 문제 Shedlock으로 해결하기

[SpringBoot] 트랜잭션 전파 속성 (Transaction propagation)

[SpringBoot] AWS S3 다중 이미지 파일 업로드 및 삭제 구현하기 (feat. MultipartFile)

[SpringBoot] @Scheduled를 이용한 스케줄러 구현

티스토리툴바

개인정보

단축키

내 블로그

블로그 게시글

모든 영역