Swagger 기본 설정 및 Nginx 설정

Swagger 적용

1. build.gradle에 의존성 추가

// Swagger
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

2.  application.yml에 프로퍼티 설정

# Swagger 설정
springdoc:
  default-consumes-media-type: application/json;charset=UTF-8 # 요청
  default-produces-media-type: application/json;charset=UTF-8 # 응답
  paths-to-match: /** # API 문서화 대상 경로 설정
  swagger-ui:
    path: /swagger-ui.html # Swagger UI 접속 경로
    display-request-duration: true # 요청 소요 시간
    groups-order: desc # API 그룹 정렬 순서
    operations-sorter: alpha # API 목록 정렬 순서 설정
    disable-swagger-default-url: true # 기본 URL 비활성화
    url: /api-docs # Swagger API 문서화 경로
  api-docs:
    groups:
      enabled: true # API 그룹화 기능 활성화
    path: /api-docs

 

💡Swagger UI의 기본 API 문서 경로는 /v3/api-docs이지만 Nginx를 통해 서비스를 배포할 때 swagger-ui/index.html에서 해당 경로의 문서가 바로 로드되지 않는 문제가 발생 -> API 문서 경로를 /v3/api-docs에서 /api-docs로 변경 후 정상적으로 문서 표시됨

Nginx 설정

location /swagger-ui/ {
        proxy_pass http://[web 내부 ip 주소]:포트/swagger-ui/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
}

location /api-docs {
        proxy_pass http://[web 내부 ip 주소]:포트/api-docs;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
}