Swagger 3.x 와 spring doc [1]

Swagger, Springdoc

api개발을 위해 Swagger를 사용했다... 옛날 버전의 swagger와 springfox를 이용했는데 이번에 전부 최신버전으로 업 하자는 말이 나와서 찾아보니 최근에는 springfox 말고 springdoc를 사용한다는 것을 알았다. 해서 해당 설정을 해볼 것이다.!

설명

RESTful API의 개발과 문서화를 도와주는 프레임워다. Swagger는 API를 작성하는 데 사용되는 다양한 언어와 프레임워크에 대한 지원을 제공하며, API의 문서화를 자동화하여 개발자와 사용자 간의 협업을 용이하게 한다.
둘은 같은 웹 인터페이스(Swagger UI)를 제공하고 Springdoc은 Spring framework에서 사용하기 쉽도록 만들어진 라이브러리이다.

---

구현

1. pom.xml 설정

...
	<properties>
			<java.version>11</java.version>
			<spring-cloud.version>3.1.5</spring-cloud.version>
		</properties>
...
        <dependency>
			<groupId>org.springdoc</groupId>
			<artifactId>springdoc-openapi-ui</artifactId>
			<version>1.6.14</version>
		</dependency>
		<dependency>
			<groupId>org.springdoc</groupId>
			<artifactId>springdoc-openapi-webmvc-core</artifactId>
			<version>1.6.14</version>
		</dependency>
...

2. application.yml 설정

해당 파일에서 springdoc.*를 보면 상당히 많은 기능들이 구현되어 있다.

주로 사용하는 기능은 

...

springdoc:
  swagger-ui:
    operations-sorter: alpha 	# alpha(알파벳 오름차순), method(HTTP메소드순)
    tags-sorter: alpha 			# 태그 정렬 기준
    path: /swagger-ui.html 		# html 문서 접속 경로
    disable-swagger-default-url: true
    doc-expansion: none 		# tag, operation 펼치는 방식
  paths-to-match:
    - /**				# swagger에서 사용할 URL 패턴을 지정

3. config java 설정

annotain 설명

@OpenAPIDefinition :  Swagger API의 메타데이터를 정의하는 annotation이다. API의 버전, 제목, 설명, 라이선스 및 기타 정보를 정의할 수 있다.

 

나는 특정 패키지나 path를 이용하여서 그룹을 만들 것이다.

 

- 패키지별

config 설정 java 파일

@OpenAPIDefinition(
		info = @Info(
				title = "TEST API",
				description = "API Document",
				version = "v0.1",
				contact = @Contact(
						name = "victory",
						email = "victory940209@gmail.com"
				)
		)
)
@Configuration
public class SwaggerConfig {

	@Bean
	GroupedOpenApi group1() {
		return GroupedOpenApi
				.builder()
				.group("group1")
				.packagesToScan("com.victory.biz")
				.build();
	}

	@Bean
	GroupedOpenApi group2() {
		return GroupedOpenApi
				.builder()
				.group("group2")
				.packagesToScan("com.victory.bizz")
				.build();
	}
}

swagger-ui 화면

-path 별

path 별로 할 때는 application.yml에 설정했던 "paths-to-match"를 빼야 한다. 

config 설정 java 파일

@OpenAPIDefinition(
		info = @Info(
				title = "TEST API",
				description = "API Document",
				version = "v0.1",
				contact = @Contact(
						name = "victory",
						email = "victory940209@gmail.com"
				)
		)
)
@Configuration
public class SwaggerConfig {

	@Bean
	GroupedOpenApi group1() {
		return GroupedOpenApi
				.builder()
				.group("path1")
				.pathsToMatch("/path1/**")
				.build();
	}

	@Bean
	GroupedOpenApi group2() {
		return GroupedOpenApi
				.builder()
				.group("path2")
				.pathsToMatch("/path2/**")
				.build();
	}
}

swagger-ui 화면

paht별로도 잘 나오는 것을 확인할 수 있다.!

 

다음은  Controller와 model(VO) 등에 설정하는 어노테이션 상세히 알아볼 것이다.

 

https://github.com/victory940209/springdoc.git

GitHub - victory940209/springdoc