[Swagger] Swagger를 이용해 API 문서를 자동으로 만들어보자

 

[Swagger] API 명세도구를 사용해보자

 

이전 포스팅에 이어, 이번에는 Swagger를 이용해서 API 문서를 자동으로 만들어보도록 한다.

아래 예제는 현재 진행중인 사이드 프로젝트를 대상으로 적용했다.

 

 

의존성 추가

---

사이드 프로젝트가 Maven 으로 의존성을 관리하고 있으므로, Maven 기준으로 설명합니다.

 

pom.xml에 아래 의존성을 추가합니다.

 

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>

 

 

Swagger Configuration 클래스 작성

---

아래와 같이 Swagger Configuration 클래스를 작성합니다.

@Configuration
@EnableSwagger2
public class SwaggerConfig
{
    @Bean
    public Docket docket ()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                    .useDefaultResponseMessages(false)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.ddng.customerapi.modules"))
                    .paths(PathSelectors.ant("/**"))
                    .build();
    }
}

• useDefaultResponseMessages
  • Swagger 에서 기본적으로 제공하는 응답코드 메시지를 표시할 지 여부
  • 만약 어떤 요청에서 200 혹은 500 응답코드만을 반환할 경우, 실제로 반환하지 않는 코드들도 표시되므로 false 로 지정했습니다.
• apis
  • 문서화할 API의 패키지를 지정하는 속성
  • BasePackage를 지정하면, 해당 패키지 하위의 컨트롤러의 @RequestMapping 어노테이션을 읽어 문서화합니다.
• paths
  • 위 apis에서 지정한 @RequestMapping 중 문서화할 Request URI를 지정하는 속성

 

 

테스트 & 트러블 슈팅

---

Configuration 클래스까지 작성한 뒤, 어플리케이션을 구동하고 http://localhost:8080/swagger-ui.html 로 접속하면 아래와 같이 자동으로 문서화된 API 를 확인할 수 있습니다.

 

 

만약, Spring HATEOAS를 사용하는 프로젝트라면, 아래 오류가 발생할 수 있습니다.

 

***************************
APPLICATION FAILED TO START
***************************

Description:

Parameter 0 of method linkDiscoverers in org.springframework.hateoas.config.HateoasConfiguration required a single bean, but 17 were found:
	- modelBuilderPluginRegistry: defined in null
	- modelPropertyBuilderPluginRegistry: defined in null
	- typeNameProviderPluginRegistry: defined in null
	- syntheticModelProviderPluginRegistry: defined in null
	- documentationPluginRegistry: defined in null
	- apiListingBuilderPluginRegistry: defined in null
	- operationBuilderPluginRegistry: defined in null
	- parameterBuilderPluginRegistry: defined in null
	- expandedParameterBuilderPluginRegistry: defined in null
	- resourceGroupingStrategyRegistry: defined in null
	- operationModelsProviderPluginRegistry: defined in null
	- defaultsProviderPluginRegistry: defined in null
	- pathDecoratorRegistry: defined in null
	- apiListingScannerPluginRegistry: defined in null
	- relProviderPluginRegistry: defined by method 'relProviderPluginRegistry' in class path resource [org/springframework/hateoas/config/HateoasConfiguration.class]
	- linkDiscovererRegistry: defined in null
	- entityLinksPluginRegistry: defined by method 'entityLinksPluginRegistry' in class path resource [org/springframework/hateoas/config/WebMvcEntityLinksConfiguration.class]


Action:

Consider marking one of the beans as @Primary, updating the consumer to accept multiple beans, or using @Qualifier to identify the bean that should be consumed


Process finished with exit code 1

 

그럴 경우에는 앞서 작성한 Swagger Configuration 클래스에서 아래와 같이 Bean을 생성해주면 됩니다.

 

@Configuration
@EnableSwagger2
public class SwaggerConfig
{

	...

	@Bean
    public LinkDiscoverers discovers() {
        List<LinkDiscoverer> plugins = new ArrayList<>();
        plugins.add(new CollectionJsonLinkDiscoverer());
        return new LinkDiscoverers(SimplePluginRegistry.create(plugins));
    }
}

 

 

---

참고 사이트 :: qastack.kr/programming/58431876/spring-boot-2-2-0-spring-hateoas-startup-issue

Spring Boot 2.2.0 Spring HateOas 시작 문제