[Java / Spring] API 문서 자동화 Swagger

📕 개요

Spring뿐만 아니라 다른 어떤 언어, 프레임워크로 백엔드를 개발했을 때,
Rest API를 개발하고 그 API에 대한 문서를 정리하여 해당 API를 사용하는 클라이언트 및 서버 개발자들에게
문서를 정리해서 공유하는것은 필수이다.

 

기존에는 노션이나 엑셀을 사용하여 정리를 했었는데

이런식으로 노션을 사용해서 정리를 했었는데

단점이 너무 많다.

• 일일이 코드에서 구현내용, 설계 내용들을 끌고와서 입력해야 한다.
• api 설계가 바뀌면 노션 문서도 수정해야한다.

그러던중 Swagger에 대해 알게 되었고, 적용해보았다.

 

 

📕 Swagger란?

Swagger 는 API를 설계하고 문서화 및 테스팅이 가능한 프레임워크이며, 무료 버전과 상용 버전 모두 존재한다.

Swagger 에는 아래 5개 기능이 포함되어있다.

• API 디자인(설계)
• API 빌드
• API 문서화
• API 테스트
• API 표준화

그리고 오픈 소스로 공개되어있는 툴은 3가지인데, 아래와 같다.

• Swagger Codegen : 서버와 클라이언트에 설계된 API 코드를 생성하는 툴
• Swagger Editor : API를 설계 및 문서화하는 툴
• Swagger UI : 설계된 API를 HTML 페이지로 확인할 수 있는 툴

 

📕 Swagger 적용

가장 많이 사용되는 2.9.2를 사용

📗 기본 설정

[build.gradle]

dependencies {
	...
	//swagger
	implementation group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
	implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
}

 

스프링 2.6 버전 이상은 application.properties에 아래 내용을 추가해야한다.

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

 

[SwaggerConfiguration]

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

    /**
     * 가장 기본적인 구조
     * https등 추가적인 기능을 하려면 문서참고
     */
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("lostark.todo"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("로스트아크 숙제 체크 사이트 REST API")
                .description("설명 부분")
                .version("1.0.0")
                .build();
    }
}

 

이 상태로 서버를 구동하고

http://localhost:8080/swagger-ui.html로 들어가보면 아래와 같은 화면이 나온다.

REST API Controller 들과 Model로 들어온 것들을 확인 할 수 있다.

 

 

📗 Swagger UI 정렬

기본적으로 Swagger UI의 정렬은 알파벳 순으로 되어있다.

여기서 알파벳 순이 아닌 GET, PATCH등의 메소드 순으로 정렬하고 싶다면

SwaggerConfiguration에 아래와 같은 내용을 추가하면 된다.

@Bean
public UiConfiguration uiConfig() {
    return UiConfigurationBuilder.builder()
            .operationsSorter(OperationsSorter.METHOD).build();
}

 

📗 API 이름 변경

위에 보이는 화면에서 

"캐릭터 관련 REST API" 와 GET 매핑중 "회원에 등록된 캐릭터리스트 가져옴"만 이름이 다른 것을 볼 수 있다.

코드를 살펴보자

@RestController
@RequiredArgsConstructor
@Slf4j
@RequestMapping("/api/character")
@Api(tags = {"캐릭터 관련 REST API"})
public class CharacterApiController {

    private final CharacterService characterService;
    private final MarketService marketService;
    private final ContentService contentService;
    private final MemberService memberService;

    @ApiOperation(value = "회원에 등록된 캐릭터리스트 가져옴",
            notes="휴식게이지를 참고하여 일일컨텐츠 수익 계산하여 함께 리턴")
    @GetMapping("/{username}")
    public ResponseEntity characterList(@ApiParam(value = "유저 네임", required = true) @PathVariable String username) {
        try {
            ...

            // 결과 출력
            CharactersReturnDto charactersReturnDto = new CharactersReturnDto();
            charactersReturnDto.setCharacters(characterReturnDtoList);
            charactersReturnDto.setSumDayContentProfit(sum);
            charactersReturnDto.setSortedDayContentProfitDtoList(sortedDayContentProfit);

            return new ResponseEntity<>(charactersReturnDto, HttpStatus.OK);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

}

• @Api(tags = {}) : 출력되는 API의 이름을 바꿀 수 있다. 
• @ApiOperation(value = "", notes="") : API에 설명을 적을 수 있다.
• @ApiParam(value = "", required = true) : API 파라미터의 설명을 바꿀 수 있다.

 

📗 Model 이름 변경

@Data
public class CharactersReturnDto {

    @ApiModelProperty(example = "기본 캐릭터 리스트")
    List<CharacterReturnDto> characters = new ArrayList<>();

    @ApiModelProperty(example = "일일 컨텐츠 수익 합")
    Double sumDayContentProfit;

    @ApiModelProperty(example = "일일 컨텐츠 수익 순으로 정렬")
    List<SortedDayContentProfitDto> sortedDayContentProfitDtoList = new ArrayList<>();
}

어떻게 출력되는지는 아래 예시에서 볼 수 있다.

 

📗 API Response 변경

api 메소드 리턴이 ResponseEntity로 되어있는데,

이것을 Swagger UI에서 확인해보면 아래와 같이 되어있다.

 

위에 코드를 보면 CharactersReturnDto로 리턴되는데 Swagger UI에서는 알 수 없다.

return new ResponseEntity<>(charactersReturnDto, HttpStatus.OK);

 

리턴 메소드를 바꾸는 방법도 있지만, 

@ApiOperation에 reponse를 따로 추가하는 방법도 가능하다.

@ApiOperation(value = "회원, 캐릭터 리스트 조회",
            notes="휴식게이지를 참고하여 일일컨텐츠 수익 계산하여 함께 리턴",
            response = CharactersReturnDto.class)

위에 Model 이름 변경에서

@ApiModelProperty(example = "기본 캐릭터 리스트")

이런식으로 example를 적어놓았기 때문에 리턴되는 값의 간략한 내용을 확인 할 수 있다.

 

📗 테스트

화면에서 테스트를 해볼 수 있다.