Spring swagger 적용

API 문서 관리의 어려움

 Rest API 서버를 개발하다 보면, API Spec에 대해 문서화를 해서 Frontend 개발자들에게 배포를 해야 한다. 보통 자체 양식으로 문서화하여 배포하는 방식이 기존의 방식이라 할 수 있다. 하지만, 이러한 방식은 문서 관리도 쉽지 않고 만드는 사람이 여러 사람이다 보니 관리가 쉽지 않다.

이에 Swagger라는게 있다. 예전에 S기업의 프로젝트를 진행하면서, Swagger라는 것을 처음 구경했다. 해당 기업은 Swagger를 통해서 기간 시스템의 정보 API를 제공하고 있었다. 사용해보니, API 정보 제공자나 API 정보 이용자나 불편함이 없었다. 이용자 입장에서는 Swagger에서 테스트도 가능하고, api의 스펙을 정확히 이해할 수 있다. 정보 제공자 입장에서는 솔직히 문서화를 별도로 할 필요가 없다.

Swagger란

아래는 wiki에 나와 있는 swagger의 소개다.

 Swagger란 개발자가  REST   웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다. 대부분의 사용자들은 스웨거 UI 도구를 통해 스웨거를 식별하며 스웨거 툴 셋에는 자동화된 문서화, 코드 생성, 테스트 케이스 생성 지원이 포함된다.

아래는 swagger 공식 사이트에서 API 문서 자동화에 대한 내용을 기술한 부분이다. 참조하자.

swagger.io/resources/articles/documenting-apis-with-swagger/

Documenting Your Existing APIs: API Documentation Made Easy with OpenAPI & Swagger

Swagger에는 문서화 뿐만 아니라 설계, 빌드를 도와주는 기능이 포함되어 있다. 이 포스팅에서는 문서화에 대한 것이므로 설계, 빌드에 대한 부분은 다음에 알아보기로 한다.

Swagger의 적용

1. 먼저 관련 라이브러리를 pom.xml 에 추가하자.

<!-- springfox-swagger2 -->
<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>

 

2. Spring security 에 swagger 관련 uri를 허용 처리한다.

 @Override
public void configure(WebSecurity web) {
        
   web
   .ignoring()
   .mvcMatchers("/swagger-ui.html/**", "/configuration/**", "/swagger-resources/**", "/v2/api-docs","/webjars/**", "/webjars/springfox-swagger-ui/*.{js,css}");
}

 

3. Swagger 설정을 추가한다.

Swagger 대상 패키지를 지정한다. 여기에서는 com.lsware.web.rest  밑에 rest controller가 위치한다. groupName은 기본적으로 하나 이상 지정하게 되어 있다. 지정하지 않으면 에러가 발생한다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {

	@Bean
	public Docket docket() {
		String groupName = "someGroupName";
		return new Docket(DocumentationType.SWAGGER_2)
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.lsware.web.rest"))
				.paths(PathSelectors.any())
				.build()
				.groupName(groupName)
				.apiInfo(apiInfo())
				;
	}

	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("Web Application Api")
				.description("New project Web Application Api ")
				.version("1.0.0")
				.license("Copyright blah blah")
				.build();
	}
}

 

4. Rest Controller에 @ApiOperation 어노테이션을 추가한다. 

/**
* OOOO의 상태를 조회
* @return
*/
@ApiOperation("상태별 OOO 조회")
@RequestMapping(value="/bystatus/get", method=RequestMethod.GET)
	public List<SomeDto> getByStatus() {
	SearchStatus searchStatus = new SearchStatus();
    
	List<SomeDto> listBlahblah = inspRsltService.listSomeStatus(searchStatus);
	return listBlahblah;
}

 

5. Swagger 를 이용한 API 문서 확인

http://localhost:8080/swagger-ui.html  을 들어가 보면 아래와 같은 API 문서 화면을 영접할 수 있다.

 

Rest에 대한 올바른 사용은 아래 포스팅을 참조하자.

augustines.tistory.com/129

RESTful 의 이해