[Spring] Springdoc-openapi 사용하여 API 문서 만들기

개요

springdoc-openapi는 Spring Boot 프로젝트의 API 스팩에 대하여 자동으로 문서 생성을 해주는 라이브러리다. json, yaml, html 등 다양한 형식의 문서를 생성한다. OpenAPI 3 스팩을 지원한다.

 

Getting Started

간단한 Spring MVC Controller를 생성한다.

@RestController
@RequestMapping("/v1.0/pets")
class PetApiController {
	private List<Map<String, Object>> pets = List.of(Map.of("name", "pet1"), Map.of("name", "pet2"));

	@GetMapping
	List<Map<String, Object>> findAll() {
		return this.pets;
	}

	@GetMapping("/{name}")
	List<Map<String, Object>> findByName(@PathVariable("name") String name) {
		return this.pets.stream().filter((m) -> name.equals(m.get("name"))).toList();
	}

	@PostMapping
	Map<String, Object> addPet(Map<String, Object> pet) {
		this.pets.add(pet);
		return pet;
	}

}

 

org.springdoc:springdoc-openapi-starter-webmvc-ui 를 추가한다. (webflux는 org.springdoc:springdoc-openapi-starter-webflux-ui)

dependencies {
	......
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'
	......
}

애플리케이션을 실행하면 Swagger-ui와 openapi 스팩을 확인할 수 있다.

 

Swagger UI

springdoc.swagger-ui.path 설정으로 path를 변경할 수 있다.

OpenAPI

springdoc.api-docs.path 설정으로 Path를 변경할 수 있다.

 

 

Actuator support

Spring boot actuator를 사용하여 actuator management 포트를 사용하여 swagger-ui와 openapi 엔드포인트를 제공할 수 있다.

애플리케이션의 보안을 위해서 보통은 actuator management 포트와 애플리케이션의 포트는 다르게 설정한다.

server.port=8080

springdoc.use-management-port=true
management.server.port=8089
management.endpoints.web.exposure.include=health, openapi, swagger-ui

swagger-ui와 애플리케이션이 다른 포트로 사용되는 경우 swagger-ui에서 CORS 오류로 API 호출 테스트가 불가능하기 때문에 아래와 같이 애플리케이션에서 actuator 주소에 대하여 CORS 예외처리를 해준다.

@Configuration
class WebConfiguration {
	@Bean
	WebMvcConfigurer corsConfiguration() {
		return new WebMvcConfigurer () {
			 @Override
			public void addCorsMappings(CorsRegistry registry) {
				 registry.addMapping("/v1.0/pets")
				 	.allowedOriginPatterns("http://localhost:8089/");
			}
		};
	}
}

 

Gradle plugin

Gradle 플러그인을 사용하면 Gradle 빌드를 사용하여 OpenAPI 3 스팩의 문서를 생성할 수 있다.

plugins {
	......
	id 'org.springdoc.openapi-gradle-plugin' version '1.9.0'
}

......

openApi {
	apiDocsUrl.set("http://localhost:8089/actuator/openapi")
}

 

$ gradlew clean generateOpenApiDocs

Gradle Tasks: generateOpenApiDocs

> Task :compileJava
> Task :processResources
> Task :classes
> Task :resolveMainClassName
> Task :bootRunMainClassName
> Task :forkedSpringBootRun
......
> Task :generateOpenApiDocs
> Task :forkedSpringBootStop

BUILD SUCCESSFUL in 7s
6 actionable tasks: 6 executed

 

빌드 완료 후 build/openapi.json 파일이 생성된다.

Gradle 플러그인 참고 : https://github.com/springdoc/springdoc-openapi-gradle-plugin