Swagger로 API문서화 하기.

Swagger를 사용하여, REST API에서 제공하는 모든 목록을 뽑아내기  작업을 시작했다.

물론.. 기존거에 추출은 아니고 시작하면서 아예 처음부터 만들어보기로.

 

우선 swagger를 사용하려면.. 구글에 정말 좋은 자료들이 많다.

나도 까먹지 않기 위해 포스팅 해두었고. 읽으려면 아래 참고

https://gomnezip.tistory.com/477

Spring 2.x 에서 Swagger 3.0.0 사용시 오류발생.

 

우선.. swagger를 나오도록 표시했을 때. API목록이 좀 잘 나와주면 좋지않을까?

이렇게 기본형 보다는..

위와 같이 기본형 보다는

내가 description을 따로 적어준다면?

위와 같이 description을 custom하면 좀 더 괜찮지 않을까?

물론 API문서 설명도 custom한다면 좀 더 낫지않을까 싶음.

그래서 다음과 같이 준비해보았다.

먼저.. api설정하는 부분

우선 api는 모조리 긁는다. 볼거는 apiInfo니까.

api()에서 docket을 build시, apiInfo를 설정해 줄 수 있다. apiInfo를 apiInfo()에서 설정한 것 처럼 나만의 custom message와 version등을 넣어주었다.

이렇게 하고 구동하면?

위와 같이 뜬다. custom message.

 

자.. 중간에 잠깐.. 샜는데.. API목록들을 표시할 때, description도 넣어주고 하면 좋으니까. 넣어보도록 하자.

먼저.. API를 수행하는 쪽 코드는 아래와 같이 작성했다.

class위에 애노테이션을 붙여주었다.

@Api(tags = "원하는 Tag이름", description = "해당 tag에 대한 설명" )
@RequestMapping("API group URL")
public class myController{
	@PostMapping("api sub url")
    @Operation( summary = "API이름", description = "API설명")
    @ApiResponses({
    	@ApiResponse(code = 코드값1, message = "해당 코드에 따른 메시지"),
        @ApiResponse(code = 코드값2, message = "해당 코드에 따른 메시지"),
        ...
    })
    public ResultDto myAPI(
    	@Parameter(name = "param1", description ="Param1에 대한 설명") String param1
    ){
    	...
        return resultDto;
    }
}

 다시.. 위에 붙였던 이미지를 다시 복붙해서 설명.

여기서 'Authentication'은 @Api( tags= "원하는태그이름"...) 의 원하는 태그 이름이다. 그 옆의 description은 Authentication옆에 기술된 설명이고.

 API목록을 확인하면, API url옆에 써있는 이름은 @Operation의 summary에 기술한 값이 표시된다.

 그걸 열어보면..

operation 애노테이션의 description은 'Process login...' << 이 텍스트이고

각 파라미터별로 이름과 설명이 친절하게 붙어준다. 아래처럼.

 

@ApiResponse에 있는 것은

이렇게 코드별 설명에 표시가 된다. 

Swagger로 API 테스트 및 문서화 하는데 많은 도움이 되고있다.

 

이제 내가 좀 더 찾아봐야할 것은.. 왜?? Dto Class는 Schema로 나오지 않는 것인지를 찾아봐야할듯.