Springboot에서 API Docs (Springdoc) 사용하는 방법 (1)

지난번에 JavaDoc이라던지 JSDoc을 사용하는 방법에 대해서 다룬적이 있었다. 이와 마찬가지 맥락으로 API Docs을 생성하는 방법도 있다. MSA가 유행을 하며 이로 구성된 시스템은 수많은 API Service를 관리해야 한다. 그리고 또한 이 API Service를 사용자들이 쉽게 이용할 수 있어야 한다. 이를 편하게 자동으로 해주는것이 OpenAPI 3.0 spec을 이용하여 구현한 Springdoc이라는 녀석이다. 어떻게 사용하는지 간단히 알아보자. (API Docs을 가능하게 해주는건 크게 Springfox Swagger와 SpringDoc 이렇게 크게 두가지가 있는데 최근 Spring에서 밀고 있는건 이름에서도 느낌이 오겠지만 SpringDoc이다. 이에 대해 자세하게 기술이 된 포스팅이 있고 궁금하다면 여기 를 참조하자.)

---

pom.xml - dependency 추가

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.4</version>
</dependency>	

위에서도 언급했듯이 Springfox Swagger를 사용하지 않고 SpringDoc을 사용한다. 최근 버전은 1.5.4 version이다. (2021. 2. 18) Springfox Swagger를 사용하지 않는다고 했지만 이것을 잘 발전시킨 모습이 SpringDoc이다. 

참고 : https://springdoc.org/

springdoc-openapi-ui를 살펴보면 swagger-ui를 포함하고 있는것을 확인할 수 있다. 그 외에도 이렇게 많은 dependency가 있음을 확인할 수 있다. 

application.yml - springdoc 설정

springdoc:
  swagger-ui:
    path: animal.html
  version: v1
  paths-to-match:
  - /bear/**
  - /dog/**

springdoc에 대한 설정은 application.yml 파일에서 할 수 있다. swagger-ui를 실행시키는데 필요한 path 정보 및 동작시킬 api들에 대해서 정의를 할 수 있다. 

DogController.java - Sample Controller

@Slf4j
@RequestMapping("/dog")
@RestController
public class DogController {
    
    @GetMapping("/eat")
    public Json<List<DogVo>> eatSomething() {
        log.debug("The dog is eating.");
        return null;
    }
    @GetMapping("/sleep")
    public Json<List<DogVo>> sleeping() {
        log.debug("The dog is sleeping");
        return null;
    }
}

Controller는 기본으로 사용할 경우 위와 같이 우리가 일반적으로 사용하는 모습 그대로 사용하면 된다. 일단 최고 간단히 Springdoc이라는 녀석이 어떤건지 보여주기 위해 그대로 사용을 하였고 뒤에 여기에 어떻게 양념을 치는지 보도록 하겠다. 필자는 /dog/** 라는 것 외에 /bear/** 에 대한 API 도 한셋 더 만들었다. 여기까지 작업이 되었다면 서버를 기동시키고 브라우저를 열어보자. 

 

http://localhost:port/v3/api-docs

{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"http://localhost:8081","description":"Generated server url"}],"paths":{"/dog/sleep":{"post":{"tags":["dog-controller"],"operationId":"sleeping","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/JsonListDogVo"}}}}}}},"/bear/sleep":{"post":{"tags":["bear-controller"],"operationId":"sleeping_1","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/JsonListBearVo"}}}}}}},"/dog/eat":{"get":{"tags":["dog-controller"],"operationId":"eatSomething","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/JsonListDogVo"}}}}}}},"/bear/eat":{"get":{"tags":["bear-controller"],"operationId":"eatSomething_1","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/JsonListBearVo"}}}}}}}},"components":{"schemas":{"DogVo":{"type":"object"},"JsonListDogVo":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"message":{"type":"string"},"result":{"type":"array","items":{"$ref":"#/components/schemas/DogVo"}},"error":{"type":"boolean"}}},"BearVo":{"type":"object"},"JsonListBearVo":{"type":"object","properties":{"status":{"type":"integer","format":"int32"},"message":{"type":"string"},"result":{"type":"array","items":{"$ref":"#/components/schemas/BearVo"}},"error":{"type":"boolean"}}}}}}

위와 같이 입력을 해보면 화면에 뿌려지기 위한 원본 데이터를 가지고 오는것을 확인할 수 있다. 

 

http://localhost:port/animal.html 입력 (application.yml에 정의한 값)

Swagger UI 동작화면

/v3/api-docs에서 가지고 온 데이터를 Swagger UI 가 화면에 뿌려주었다. 

위의 Controller 에서 API Docs에 관련된 아무런 것도 작성하지 않았기에 내가 지정한 path에 해당하는 API 에 대한 정보만 볼 수 있다. 이런식으로 아주 간단하게 Springdoc을 이용하는 방법에 대해 알아보았다. 다음 시간에는 어떻게 Springdoc을 사용하는지 상세한 방법 대해서 알아보겠다. 

 

Springboot에서 API Docs (Springdoc) 사용하는 방법 (2)