Swagger Springboot 3.x Operation 설정 방법

Swagger Springboot 3.x Operation 설정 방법입니다.

 

Swagger 의 다양한 설정 방법은 아래의 Link를 확인하세요!

 

Link : https://aljjabaegi.tistory.com/713

Swagger Springboot 3.x 의존성 주입 및 Information 설정, 기본 설정

 

Link : https://aljjabaegi.tistory.com/715

Swagger Springboot 3.x Response 설정 방법

 

Link : https://aljjabaegi.tistory.com/716

Swagger Springboot 3.x Spring.properties 설정 옵션

 

Link : https://aljjabaegi.tistory.com/717

Swagger Springboot 3.x JWT 인증 적용 방법

 

Link : https://aljjabaegi.tistory.com/718

Swagger Springboot 3.x Grouping 방법

 

Operation 설정

이제 실제 기능을 담당하는 Operation을 추가해 보겠습니다.

아래와 같이 Controller를 추가할 경우 Swagger에는 자동으로 Operation이 추가되게 됩니다.

 

MemberController.java

package com.aljjabaegi.swagger.api.domain.member;

import com.aljjabaegi.swagger.api.domain.member.record.MemberResponse;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MemberController {

    @GetMapping(value = "/members/{memberId}", produces = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<MemberResponse> getMember(@PathVariable("memberId") String memberId) {
        return ResponseEntity.ok(new MemberResponse("geonlee", "이건"));
    }
}

 

MemberResponse.java

package com.aljjabaegi.swagger.api.domain.member.record;

public record MemberResponse(
        String memberId,
        String memberName) {
}

 

 

 

보고 개발을 할 순 있겠지만, 매우 불친절 합니다.

친절한 Operation으로 바꿔보도록 하겠습니다.

 

@RestController
@Tag(name = "[API-001] 멤버 정보 조회, 편집", description = "[담당자 : GEONLEE]")
public class MemberController {

    @GetMapping(value = "/members/{memberId}", produces = MediaType.APPLICATION_JSON_VALUE)
    @Operation(summary = "멤버 정보 조회", description = """
            # Parameters
            - memberId [멤버 ID] <font color='red'>*</font>
            - memberName [멤버 이름]
            """,
            operationId = "API-001-01"
    )
    public ResponseEntity<MemberResponse> getMember(@PathVariable("memberId")
                                                    @Parameter(name = "memberId", description = "멤버 ID", example = "geonlee")
                                                    String memberId) {
        return ResponseEntity.ok(new MemberResponse("geonlee", "이건"));
    }
}

 

operationId 가 표출 될 수 있게 application.yml 에 아래 옵션도 추가합니다.

springdoc:
  swagger-ui:
      display-operation-id: true

 

Swagger 에서 제공하는 정보 외에, 의사소통을 도울 수 있도록 OperationId와 담당자 정보도 추가하였습니다.

 

Github Swagger Project

https://github.com/aljjabaegiProgrammer/swagger-api

GitHub - aljjabaegiProgrammer/swagger-api: swagger API project