스프링부트 API 문서화 swagger

postman에서는

문서화 하기

 

다음 항목을 눌러주면 API에 대한 설명을 추가해 줄 수 있음

---

 

—swagger—

api 문서화 + api 테스트

 

swagger를 사용하기 위해 build.gradle에 의존성 추가

// https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-annotations
implementation 'io.swagger.core.v3:swagger-annotations:2.2.22'

 

application.properties 설정에 다음 추가

#Swagger UI
springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

 

 

http://localhost:9090(8080)/swagger-ui.html로 접속하면, 위에서 만들어 둔 api를 ui로 볼 수 있다.

각각 api를 눌러

postman에서 send 보내는 것처럼 테스트해 볼 수 있다.

 

설정한 parameter 에 맞게 요청보내주기

요청에 따른 Response body와 head에 담긴 내용을 확인할 수 있음.

 

위에서 의존성, properties 추가해 주면

더 편리하게 api 문서를 작성하도록 swagger에서 제공하는 어노테이션을 사용할 수 있다.

 

 

스웨거에서 제공하는 annotation

@Operation : API 설명 추가
@ApiResponses : 상태 코드에 대한 설명 추가
    @ApiResponse : 각각 상태 코드에 대한 설명 추가
    @Content : 리턴타입 지정해줄 수 있음
    @Schema : 어떤 형태로 테이터가 리턴되는지
    
    @Parameter(description) : 파라미터에 대한 설명 추가해주기

 

다음과 같이 사용해 줄 수 있음

swagger - annotation사용하기

 

 

위에서 @Operation(summary = Member 등록)으로 작성해 주어 POST 요청에 API 요약으로 어떤 API인지 기술된다.

메서드의 매개변수부분에 @Parameter(description) 작성으로 api 호출 파라미터에 대한 설명 추가

 

http://localhost:9090(8080)/v3/api-docs

url로 접속하면

작성한 API (문서)에 대해 json 형태로 볼 수 있다.

api문서 json으로 보기

처음 접속하면 위 사진보다 구린 모양인데,

크롬 확장프로그램으로 json view 설치하면 보기 좋아진다.

 

 

지금은 따로 설정하지 않았지만, (설정하지 않아도 동작은 함) swagger config 파일도 추가해 주어

어떤 API에 대한 설정인지, 설명과 적용할 경로 등을 지정해 줄 수 있다.

config파일 작성을 습관화해서 문서의 명확성, 가독성을 높여주자.