[Api] API문서 작성

API문서 작성용 스웨거 에디터

https://editor.swagger.io/

Swagger Editor

 

API Document 작성

STS3사용 중이고 스프링 버전이 낮아 Swagger2로 API 명세서를 작성하려고 한다

 

먼저 pom.xml에 의존성 추가

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

 

SwaggerConfig클래스 생성

package ncdc.cancermonitor.cmmn;

import java.util.HashSet;
import java.util.Set;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
			.title("CancerMonitoring") // 문서 제목
			.description("API Document") // 문서 설명
			.version("1.0") // 버전
			.build();
	}
	
	private Set<String> getConsumeContentTypes() {
		Set<String> consumes = new HashSet<>();
		consumes.add("application/json;charset=UTF-8");
		consumes.add("application/x-www-form-urlencoded");
		return consumes;
	}
	
	private Set<String> getProduceContentTypes() {
		Set<String> produces = new HashSet<>();
		produces.add("application/json;charset=UTF-8");
		return produces;
	}
	
	@Bean
	public Docket commonApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.consumes(getConsumeContentTypes())
				.produces(getProduceContentTypes())
				.apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.any())
				.paths(PathSelectors.ant("/surveilance/**")) // Controller에서 Document할 URI 범위 지정
				.build();
	}

}

 

Controller작성

...
import io.swagger.annotations.ApiOperation;
...
	@SuppressWarnings("unchecked")
    // ApiOperation은 Swagger용 어노테이션으로 API 문서에서 식별 가능하게 명명해줌
	@ApiOperation(value="지역별 암 발생 현황", notes="지역별 암 발생 현황")
	@RequestMapping(value = "/map/cancerData", produces = "application/json; charset=utf-8")
	public @ResponseBody String selectMapData(HttpServletRequest request, HttpServletResponse response,
			@RequestParam HashMap hMap, Model model, HttpSession session) throws IOException, Exception {
	...
	}
...

 

이렇게 하면 전체적인 틀은 잡았다고 한다. 그래서 테스트를 했는데....

api-docs는 들어가 지는데 ui는 404에러 발생

 

참고> Swagger주소(Swagger 버전마다 다름 / Swagger2는 아래와 같다)
만약 8080포트를 사용하고 별도의 URI설정을 하지 않았을 경우
API 주소 : http://localhost:8080/v2/api-docs
UI 주소 : http://localhost:8080/swagger-ui.html

 

만약 api-docs까지 접근이 안된다면 config클래스를 잘못 생성했을 가능성이 크다고 하는데 일단 나는 api-docs까진 잘 들어가짐

 

Swagger옵션 사용법

 

useDefaultResponseMessages 옵션 

// true : Swagger에서 제공해주는 기본 응답코드(200, 401, 403, 404) 노출(default)
// false : 기본 응답코드 노출안함
.useDefaultResponseMessages(true)

 

apis 옵션

// 특정 위치 내의 컨트롤러에 대한 api화
.apis(RequestHandlerSelectors.basePackage("com.example.demo"))

// 모든 위치의 컨트롤러에 대한 api화
.apis(RequestHandlerSelectors.any())

 

paths 옵션

// 하나의 URI 파라미터 기준으로 하위 URI에 대한 doc 생성
.paths(PathSelectors.ant("/sample/**"))

// 두개의 URI 파라미터 기준으로 doc 생성
.paths(PathSelectors.regex("/(sample1|sample2)/.*"))
// 응용으로 특이한 사용법으로 URI의 앞에 파라미터만 바뀌고 뒤는 동일하다면 이런식으로 사용가능
//.paths(PathSelectors.regex("/(sample1|sample2)/common.*"))
// 이렇게 사용하면 /sample1/common/*과 /sample2/common/*을 둘다 사용할 수 있다.

// 모든 URI에 대한 doc 생성
.paths(PathSelectors.any())

  

+ ) 뭐가 문제인지 PathSelectors.regex옵션도 먹통이라 그룹을 나눠서 API문서화 시킴

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	
    ...

	@Bean
	public Docket api1() {
    	return new Docket(DocumentationType.SWAGGER_2) // Swagger 2.0 기반의 문서 작성
				.consumes(getConsumeContentTypes())
				.produces(getProduceContentTypes())
				.groupName("sample1") // 그룹지정
				.apiInfo(apiInfo())
				.select() // ApiSelectorBuilder를 반환하며 상세한 설정 처리
				.apis(RequestHandlerSelectors.any()) // 대상으로하는 api 설정
				.paths(PathSelectors.ant("/sample1/**")) // controller에서 swagger를 지정할 대상 path 설정
				.build(); // Docket 객체 생성
	}
	
	@Bean
	public Docket api2() {
    	return new Docket(DocumentationType.SWAGGER_2) // Swagger 2.0 기반의 문서 작성
				.consumes(getConsumeContentTypes())
				.produces(getProduceContentTypes())
				.groupName("sample2") // 그룹지정
				.apiInfo(apiInfo())
				.select() // ApiSelectorBuilder를 반환하며 상세한 설정 처리
				.apis(RequestHandlerSelectors.any()) // 대상으로하는 api 설정
				.paths(PathSelectors.ant("/sample2/**")) // controller에서 swagger를 지정할 대상 path 설정
				.build(); // Docket 객체 생성
	}
	
}

 

++ ) 그럼에도 개선되지 않아 차선책으로 찾은 방법

api 주소에서 JSON데이터가 나오면 우클릭으로 JSON파일로 저장

https://editor.swagger.io/에서 상단 탭중 File\import File로 JSON파일 추가하여 문서를 시각화시켰다.

Swagger Editor