[Tool/Swagger] 문서 작성법

Swagger 버전 및 의존성

Springdoc-openapi를 사용한OpenAPI 3.0 스펙을 바탕으로 글을 작성했다.

gradle의존성은 다음과 같다.

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

 

1.  Operation 설정 및 모델 객체 필드 설명

@Operation(summary = "User login", description = "사용자 입력해보세용",
            requestBody = @RequestBody(content = @Content(mediaType = "application/json", schema = @Schema(implementation = UserSwagger.class))))
@PostMapping(value ="/user3/{id}")
public UserSwagger postUser3(@PathVariable Long id, @RequestBody UserSwagger user) {
    return user;
}

Operation은 api문서에 설명을 적을 수 있다.

• summary : 엔드포인트 간단 설명
• description : 엔드포인트 상세 설명
• @Content : 메타 데이터 정의 및 schema설정
• mediaType : 메타 데이터 설정 생략 가능
• schema : 필요한 객체 지정

@Schema(description = "스웨거 설명용 사용자")
@Getter
class UserSwagger {
    Integer id = 2759;
    @Schema(description = "사용자 이름", required = true, example = "잠자고싶어요")
    String name = "gnoDgnoD";
    @Schema(description = "사용자 이메일", required = true, example = "user@example.com")
    String email = " Aleph@tistory.com";
}

@Schema를 통해서 객체의 필드값설명을 추가할 수 있다.

• description : schema에서 설명할 필드의 값
• example : example Value에 들어갈 예시 값

2.  각각의 파라미터별 문서 작성하는 방법

1. @PathVariable

@GetMapping("/user/{id}")
public String getPathVariable(
        @Parameter(description = "사용자 id", required = true) 
        @PathVariable String id) {
    return id;
}

Request: GET /user/123

2. @ RequestParam

@GetMapping("/uesr")
public String getRequestParam(
        @Parameter(description = "쿼리를 입력해주세요") 
        @RequestParam String name) {
    return name;
}

Request: GET /user?name=Name

3. @RequestBody

@PostMapping("/user")
@Operation(summary = "사용자 로그인", description = "사용자 로그인 api입니다.",
        requestBody = @RequestBody(description = "사용자 정보를 입력해주세요", required = true, 
            content = @Content(schema = @Schema(implementation = CreateUser.class))))
public String createItem(@RequestBody CreateUser user) {
    return "Created user: " + user;
}

이때 implementation으로 User.class를 받는데 User.class에 설명을 추가할 수 있다.

@Schema(description = "사용자 생성용 클래스")
@Getter
class CreateUser {
    @Schema(description = "사용자 이름", required = true, example = "잠자고싶어요")
    String name = "gnoDgnoD";
    @Schema(description = "사용자 이메일", required = true, example = "user@example.com")
    String email = " Aleph@tistory.com";
}

4. @RequestHeader

@GetMapping("user")
public String getRequestHeader(
        @Parameter(description = "Authorization token") 
        @RequestHeader("Authorization") String authorization) {
    return authorization;
}

Request: GET /request-header 의 헤더에 담겨있는 Authorization: Bearer token

5. @CookieValue

@GetMapping("/user")
public String getCookieValue(
        @Parameter(description = "Session id값을 가져옴") 
        @CookieValue("sessionId") String sessionId) {
    return sessionId;
}

Request: GET /user의 쿠키에 담겨있는 Cookie sessionId=abc123

6. @ModelAttribute

@PostMapping("/user")
public String createWithModelAttribute(@ModelAttribute Item item) {
    return item;
}

Request: POST /user 에 에 있는 Model값

7. @RequestPart

@PostMapping("/user")
public String uploadFile(
        @Parameter(description = "업로드할 파일") 
        @RequestPart("file") MultipartFile file) {
    return file.getOriginalFilename();
}

 

Operation과 각각의 파라메터 별 문서 작성법을 둘다 사용하면 된다!