[API] Spring boot Swagger 기본 사용법

https://swagger.io/

API Documentation & Design Tools for Teams | Swagger

Swagger UI 란 ?

별도의 코드 추가 없이 OpenAPI 규격에 맞게 자동으로 API를 시각화 시켜준다.

Spring - Rest API를 개발 하고 API에 대한 문서를 정리 / 공유해야 할 때 Swagger를 사용하면 보다 편리해진다.

API 문서 자동화 뿐만 아니라 UI에서 직접 API 테스트도 가능하다.

 

 

개발환경

 

Spring Boot

Maven

Java 8

Swagger 2.9.2

 

 

Swagger 의존성 추가 - pom.xml

 

<!-- swagger -->
<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 설정 추가 - SwaggerConfig

 

@Configuration // 설정 파일 읽어오기
@EnableSwagger2 // Swqgger2 활성화
public class SwaggerConfig {
	
   	// API별 구분 짓기
	@Bean
	public Docket allApi() {
		return getDocket("전체", Predicates.or(PathSelectors.regex("/*.*")));
	}
	
	@Bean
	public Docket menuApi() {
		return getDocket("메뉴", Predicates.or(PathSelectors.regex("/패키지 경로")));
	}

	@Bean
	public Docket codeGroupApi() {
		return getDocket("코드 그룹", Predicates.or(PathSelectors.regex("/패키지 경로")));
	}

	// Swagger 설정
	public Docket getDocket(String groupName, Predicate<String> predicate) {
		return new Docket(DocumentationType.SWAGGER_2)
			.apiInfo(apiInfo())
			.useDefaultResponseMessages(false) // Default Response Message 삭제 - 기본값 true
			.groupName(groupName)
			.select() // ApiSelectorBuilder 생성
			.apis(RequestHandlerSelectors.basePackage("패키지 경로")) // 문서화 할 패키지 지정
			.paths(predicate) // apis() 조건에 맞는 API 문서화 - PathSelectors.any() : 전체 패키지
			.build()
			.globalResponseMessage(RequestMethod.GET, getCustomizedResponseMessages())
            		.globalResponseMessage(RequestMethod.POST, getCustomizedResponseMessages())
             		.globalResponseMessage(RequestMethod.DELETE, getCustomizedResponseMessages())
            		.globalResponseMessage(RequestMethod.PUT, getCustomizedResponseMessages())
             		.globalResponseMessage(RequestMethod.PATCH, getCustomizedResponseMessages());
	}
	
    	// Swagger UI 설정
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
			.title("제목")
			.version("0.0.1")
			.description("내용")
			.contact(new Contact("URL명", "URL", "이메일 연동"))
			.build();
	}
	
   	 // ResponseMessage 설정 - 원하는 ErrorCode + message 지정
	 private List<ResponseMessage> getCustomizedResponseMessages() {
		List<ResponseMessage> responseMessages = new ArrayList<>();
        	responseMessages.add(new ResponseMessageBuilder().code(200).message("성공 하였습니다.").build());
       		responseMessages.add(new ResponseMessageBuilder().code(400).message("잘못된 접근입니다.").build());
        	responseMessages.add(new ResponseMessageBuilder().code(404).message("페이지를 찾을 수 없습니다.").build());
        	responseMessages.add(new ResponseMessageBuilder().code(500).message("내부 서버 오류가 발생하였습니다.").build());
        
       		return responseMessages;
	}
}

 

서버 실행 후 아래 형태의 주소로 접속한다.

localhost:[port]/swagger-ui.html

 

해당 페이지가 보이고 아래는 각자 갖고있는 Controller가 자동 연결 된다.

 

 

Swagger Controller 적용

* Swagger 검색 시 모든 블로그에 예시 이미지가 있어 별도 캡처하지 않음.

 

@RestController
@Api(tags="코드 그룹") // 대제목 지정
public class CodegroupController {

	@Autowired
	private CodegroupService codegroupService;
	
	/** 코드 그룹 목록 조회*/
	@GetMapping(value="/codegroup")
	@ApiOperation(value="코드 그룹 목록 조회", notes="<strong>코드 그룹 목록을 조회합니다.</strong>") // 각 API(메소드)명칭/설명 추가
	@ApiImplicitParam(name="params", value="코드 그룹 리스트") // 해당 API Method 호출에 필요한 Parameter 명칭/설명 추가
	public ResponseEntity<Object> getCodegroupList(@RequestParam Map<String, Object> params ) {
		생략;
	}

 

@Api - 각 패키지별 대제목 지정

 

@ApiOperation - 각 API(Method) 명칭/설명 추가

 

@ApiImplicitParam - 해당 API Method 호출에 필요한 Parameter 명칭/설명 추가

 

• dataType, paramType, required 는 자동 지정되어 생략 가능하다.
• paramType의 경우 @RequestParam 은 query , @PathVariable 은 path 로 명시 해주면 된다.
• 해당 Method의 Parameter가 복수일 경우 @ApiImplicitParams 로 @ApiImplicitParam을 사용하면 된다.

* 복수 사용 예제

	/** 코드 그룹 수정*/
	@PutMapping(value="/codegroup/{codegroupId}")
	@ApiOperation(value="코드 그룹 수정", notes="<strong>코드 그룹을 수정합니다.</strong>")
	@ApiImplicitParams({
		@ApiImplicitParam(name="codegroupId", value="코드 그룹 ID", required=true),
		@ApiImplicitParam(name="params", value="코드 그룹 리스트", required=true)
	})
	public ResponseEntity<Object> modifyCodegroup(@PathVariable(name="codegroupId") String codegroupId, @RequestBody Map<String, Object> params) {
		생략;
	}

 

 

@ApiResponse - 해당 Method의 Response 내용 변경

 

• Config 에서 ResponseMessage 처리 하는 것과 동일하다.
• 각 Method별 에러코드 별도 지정이 가능하다. (코드가 길어짐)
• @ApiImplicitParam과 동일하게 복수 사용이 가능하다.

	/** 코드 그룹 목록 조회*/
	@GetMapping(value="/codegroup")
   	@ApiResponses({
   	 	@ApiResponse(code=200, message="성공입니다."),
		@ApiResponse(code=400, message="비정상적인 접근입니다.")
  	})
	public ResponseEntity<Object> getCodegroupList(@RequestParam Map<String, Object> params ) {
		생략;
	}

 

* 동일 Response Message를 Controller method 전체에 적용하고 싶다면

 

@ApiResponses({@ApiResponse(code=200, message="성공 하였습니다.")})
public class CodegroupController {
	...
}

 

method가 아닌 Controller단에 @ApiResponses를 적용해주면 된다.

 

 

* 상태 코드 참고

코드	설명	코드	설명
200	성공	400	잘못된 요청
201	작성됨	401	권한 없음
202	허용됨	403	금지됨
301	영구 이동	404	찾을 수 없음
303	기타 위치 보기	410	사라짐
304	수정되지 않음	500	내부 서버 오류
307	임시 리다이렉션	503	서비스를 사용할 수 없음

 

 

@ApiParam - DTO(VO) Field 명칭 지정

 

• @ApiImplicitParam 과 동일하다. ( @ApiParam은 DTO(VO)에서 지정 )

	@ApiParam(value="코드 ID")
	private String codeID;
    
    	@ApiParam(value="코드명")
	private String codeName;

 

• Controller에서 Param값에 바로 적용도 가능하다. (추천하진 않음)

	/** 코드 그룹 목록 조회*/
	@GetMapping(value="/codegroup")
	public ResponseEntity<Object> getCodegroupList(@ApiParam(value="코드 그룹 리스트") @RequestParam Map<String, Object> params ) {
		생략;
	}

 

 

@ApiModelProperty - DTO(VO) Response 예제 설명 추가

 

• 해당 DTO(VO) Field의 예제 Data를 추가 할 수 있다.
• 응답 받는 데이터 값을 쉽게 알 수 있다.
• name은 생략 가능하다.

	@ApiModelProperty(name="codeID" example="코드 ID")
	private String codeID;

	@ApiModelProperty(example="코드명")
	private String codeName;

 

 

Reperence

https://github.com/swagger-api/swagger-core/wiki/Annotations

GitHub - swagger-api/swagger-core: Examples and server integrations for generating the Swagger API Specification, which enables