Spring Doc을 이용한 swagger 추가

Spring Doc 사용 -> 내부적으로 swagger를 사용한다.

• 실행하고 밑의 주소로 이동하면 자동으로 swagger api 문서가 생성된다.

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

• 단점

  • get을 호출할경우 403이 나올 수있음
    -> header 값을 조정할 수 없어서(header에 토큰 값이 필요한 경우에는 403에러가 발생한다.

  -> 밑에서 다시 다룰 예정

Swagger 문서 꾸미기

• Tag 어노테이션을 통해서 이름을 바꿀수 있고 ,설명을 적어줄 수 있다.
• 내부에있는 api를 꾸미는 경우 operation 어노테이션으로 내용을 요약해서 알려줄 수있음.

• 위의 이미지와 같이 api에 어떤 것 이 가능한지를 알려줄 수 있게된다.

---

추가로 SpringDocConfig를 만들어서

이 부분 설정도 가능하다. 밑의 코드를 통해서 OpenAPiDefinition을 통해서 info와 version을 설정할 수 있다.

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.context.annotation.Configuration;

@Configuration
@OpenAPIDefinition(info = @Info(title="REST API",version = "v1"))
public class SpringDocConfig {
}

위의 설정을 넣어줌으로서 swagger문서가 설정된 모습이다.

---

Swagger에서 헤더에 값을 설정하는 방법

• 스웨거 헤더에 엑세스 토큰 설정할 수 있도록 하는 방법

---

SpringDocConfig에 SecurityScheme를 추가해준다.
name : 스키마 이름 지정

type : 보안 스키마의 유형 지정 -> HTTP 타입 사용중

bearerFormat : Bearer토큰 형식 지정 -> 현재는 JWT 토큰

scheme : HTTP 스키마를 지정 -> bearerToken을 사용중이므로 bearer로 지정

---

토큰이 필요한 부분 Operation 어노테이션에 SecurityRequirement를 추가해준다

위와 같이 설정할 경우 현재 설정한 api에 자물쇠부분이 생기게 되고 저 자물쇠를 클릭하면 bearerAuth Value를 넣을 수 있게된다. -> bearerFormat이 JWT 이기 때문에 로그인하면서 발급받은 JWT 토큰을 넣어주면 Swagger에서도 테스트가 가능해진다.

토큰값을 넣으면 자물쇠가 잠긴다.

• 토큰 값을 잘못 넣는 경우

• 로그인하면서 발급받은 토큰이 아닌 경우

• postMan에서 나온것과같이 403에러가 발생한다

{
  "timestamp": "2023-08-21T08:16:16.818+00:00",
  "status": 403,
  "error": "Forbidden",
  "message": "Access Denied",
  "path": "/api/v1/member/me"
}

• 발급받은 토큰을 제대로 넣는 경우

• 성공하고 현재 로그인한 사람의 정보를 보여준다.

• {
    "resultCode": "S-1",
    "msg": "성공",
    "data": {
      "member": {
        "id": 2,
        "regDate": "2023-08-21T17:10:03.174218",
        "username": "user2"
      }
    }
  }

---

git : https://github.com/YunJiW/restApi_2023/commit/fe59534ee00a07d8eb330ef819834d977e516f7f

Swagger 참조 : https://swagger.io/docs/specification/authentication/