1. 의도
- 이번 프로젝트는 msa구조의 통합 문서를 관리를 위해 swagger를 이용하여 문서 작업을 하려고 합니다. 이전 프로젝트에서는 API문서를 이용하여 개발을 했습니다. 하지만 Request, Response 등 수정이 필요할 때마다 여러 문서 작업을 해야하는 불편함을 느껴 개선하고자 swagger를 이용한 문서 작업을 생각 했습니다.
문제점
- 각각의 마이크로 서비스도 swagger를 만들어 Gateway로 이어주는 방법을 생각했습니다. 하지만 해당 방법이 아니고 API 명세(json)를 가져와 동적으로 데이터를 gateway로 줌으로써 gateway의 swagger에서 html를 변경해준다는 것을 알 수 있었습니다
2. Spring Cloud Gateway 설정
spring cloud gateway를 이용하여 여러 마이크로 서비스 swagger를 연결하고자 합니다.
1) 의존성(gradle) 추가
implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webflux-ui', version: '2.2.0'2) Gateway를 통해 마이크로 서비스를 연결 경로 설정
- 2.1) Gateway를 통해 서비스 포트 연결 yml
- 2.2) Swagger를 service 연결 시키기
use-root-path=true를 통해 gateway포트를 접근하면 swagger로 바로 접근할 수 있습니다
definition를 통해 gateway에 연결된 서비스에 접근할 수 있습니다
GateWay의 설정은 완료!
3. 마이크로 서비스 연결
여기서 의문점이 생겼던 부분이 각각의 마이크로 서비스도 swagger를 통해 연결해주는 방법이라고 생각했습니다. 그로인해 각각의 서비스도 swagger를 만들고자 했지만 json형태로 데이터를 gateway로 줘야한다는 것을 알 수 있었습니다
1) 의존성(gradle) 추가
implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webflux-ui', version: '2.2.0'2) Gateway로 연결된 서비스 포트로 연결( ※ API접근시 JSON 형태로 수락과 응답으로 반환)
3) 서비스는 각각의 swagger를 만들기 보다는 JSON 타입으로 반환해줘야 한다(해당 내용을 gateway의 swagger가 읽어 html로 보여준다)
- 개인 마이크로 서비스의 포트로 접근하여 json형태 수락과 응답
- gateway의 springdoc-url과 path가 같아야 한다
4) config 연결
@RequiredArgsConstructor
@Configuration
@OpenAPIDefinition(
info = @Info(title = "API Document", description = "MAIL SERVICE 명세서", version = "v3")
)
public class SwaggerConfig {
@Bean
public OpenAPI openAPI() {
return new OpenAPI()
.addServersItem(new Server().url("/"));
}
}여기서 서버의 url을 /로 설정하는 것은 해당 서버를 배포하였을 때, 서버가 https로 설정되어 있을 경우에 swagger를 통해 API 요청시에, http, https 간의 통신에서 cors와 같은 문제가 발생할 수 있어서, url을 root 경로로 설정해서 이를 방지하기 위해서 입니다.
완료
