[springdoc-openapi-ui] Springdoc 적용하기

따용·2023년 4월 14일
0

백엔드

목록 보기
2/4

개발 환경
Maven, Spring Boot, Java

1. Spring Boot 버전 확인하기

pom.xml 파일에서 Spring Boot의 버전을 확인한다.

 <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.6.14</version>
  </parent>

⭐ Spring Boot 버전이 3이상
springdoc-openapi v2.1.0 적용

⭐ Spring Boot 버전이 3미만
springdoc-openapi v1.7.0 적용

나는 spring boot버전이 3미만이라서 v1.7.0을 적용했다.
버전이 다르면 swagger페이지에 접속할 수 없기 때문에 꼭 버전확인을 한 후에 적용해야한다.

2. pom.xml 파일에 종속성 추가하기

<!-- springdoc-openapi 라이브러리 추가 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>
<!-- /api-docs에서 json형식으로 보여주기 위해 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-webmvc-core</artifactId>
    <version>1.7.0</version>
</dependency>

3. application-properties 파일에 설정 추가

아래 설정 값에서 필요한 설정만 추가한다.
이 외에도 많은 설정들이 있는데 설정은 Springdoc-openapi Properties 를 참고

# swagger custom 주소(default 주소인 /swagger-ui/index.html 로 설정할 수 없다)
springdoc.swagger-ui.path=/swagger-ui
# /api-docs endpoint custom path
springdoc.api-docs.path=/api-docs
# tag sorter
springdoc.swagger-ui.tags-sorter=alpha
# request media type
springdoc.default-consumes-media-type=application/json;charset=UTF-8
# response media type
springdoc.default-produces-media-type=application/json;charset=UTF-8
# 확장하지 않기
springdoc.swagger-ui.docExpansion="none"
# auth 유지
springdoc.swagger-ui.persistAuthorization=true
# 페이지 마지막에 보여지는 schema hidden
springdoc.swagger-ui.defaultModelsExpandDepth=-1
# fully qualifed name (Schema를 전체 경로로 가져오기)
springdoc.use-fqn=true

참고:
👉 springdoc.swagger-ui.path 설정
설정하지 않으면 ${주소}/swagger-ui.html로 접근, 나는 경로를 http://localhost:8080/swagger-ui 로 접근할 수 있도록 설정했다

👉 springdoc.use-fqn=true
스키마 설정 시 파일을 Token.GetRequest.class, Project.GetRequest.class 이런 식으로 사용했는데 이 경우 먼저 선언된 GetRequest만 불러와서 보여주는 현상이 발생
검색해보니 Swagger에서 전체 클래스를 불러와서 처음 불러온 값과 똑같은 클래스를 보여주기때분에 발생하는 현상이라고 함
springdoc.use-fqn을 사용하면 전체 경로로 스키마를 불러오기 때문에 해당 오류가 사라짐

⚠️ 해결책 참고
https://effortguy.tistory.com/203
https://github.com/springdoc/springdoc-openapi/issues/548

4. Config 파일 생성

package com.web.config;

import org.springdoc.core.GroupedOpenApi;
import org.springdoc.core.customizers.GlobalOpenApiCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.media.Content;
import io.swagger.v3.oas.models.responses.ApiResponse;
import io.swagger.v3.oas.models.responses.ApiResponses;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeIn;

@Configuration
@SecurityScheme(type = SecuritySchemeType.APIKEY, name = "Access-Token", in = SecuritySchemeIn.HEADER)
@OpenAPIDefinition(security = { @SecurityRequirement(name = "Access-Token") })
public class SwaggerConfig {

	@Bean
	public GroupedOpenApi publicApi() {
    		// pathsToMatch로 원하는 경로의 api만 나오도록 설정
			return GroupedOpenApi.builder()
							.group("v1")
							.pathsToMatch("/v1/**")
							.build();
	}

	@Bean
	public OpenAPI springShopOpenAPI() {
		String title = "Swagger Page Title";
		String description = "Swagger Page Description";

		Info info = new Info().title(title).description(description).version("1.0.0");

		return new OpenAPI().info(info);
	}

	public ApiResponse createApiResponse(String message, Content content){
		return new ApiResponse().description(message).content(content);
	}

	@Bean
	public GlobalOpenApiCustomizer customerGlobalHeaderOpenApiCustomiser() {
		return openApi -> {
        	// 공통으로 사용되는 response 설정 
			openApi.getPaths().values().forEach(pathItem -> pathItem.readOperations().forEach(operation -> {
				ApiResponses apiResponses = operation.getResponses();
				apiResponses.addApiResponse("200", createApiResponse(apiResponses.get("200").getDescription(), apiResponses.get("200").getContent()));
				apiResponses.addApiResponse("400", createApiResponse("Bad Request", null));
				apiResponses.addApiResponse("401", createApiResponse("Access Token Error", null));
				apiResponses.addApiResponse("500", createApiResponse("Server Error", null));
			}));
		};
	}
}

5. 설정한 링크로 Swagger 페이지 접근

profile
🤫

0개의 댓글