spring api docs 문서화

Spring REST Docs를 이용하면 테스트 후에 작성된 snippet을 이용해서 문서를 만들기 때문에 정확하다.

curl이나 http 등의 샘플도 자동으로 생성해준다.

Spring 공식 문서들은 이미 Spring REST Docs로 작성되어있다.

https://docs.spring.io/spring-restdocs/docs/current/reference/html5/

Spring REST Docs

 

어떤 프로젝트들은 Swagger를 통해서 API 문서를 작성해서 Swagger UI를 통해서 실행가능한 것에 대한 장점을 활용한다.

여러 장점들이 있듯이 단점도 존재하는데 실행 코드에 문서를 위한 애너테이션이 많이 추가되어서 가독성이 떨어진다.

@ApiOperation(notes = "Operation 2", value = "${SomeController.operation2.value}"...) 
@ApiImplicitParams(
  @ApiImplicitParam(name="header1", value="${SomeController.operation2.header1}", ...) 
)
@RequestMapping(value = "operation2", method = RequestMethod.POST)
public ResponseEntity<String> operation2() {
  return ResponseEntity.ok("");
}

 

https://springfox.github.io/springfox/docs/current/

Springfox Reference Documentation

 

아래 library를 이용하려고 했으나 TestCase를 변경해줘야되는 부분이 있다.

적용하는 부분은 간단해보이진 않음. 그래서 다른 걸 찾음.

https://github.com/ePages-de/restdocs-api-spec#openapi-301

GitHub - ePages-de/restdocs-api-spec: Adds API specification support to Spring REST Docs

 

springdoc openapi library를 이용하면 쉽게 swagger-ui 제공하고 api-docs endpoint를 생성해준다.

아래 의존성을 추가하고 바로 실행해보자

implementation 'org.springdoc:springdoc-openapi-ui:1.6.9'

 

기본 위치

http://server:port/context-path/swagger-ui.html 
http://server:port/context-path/v3/api-docs

대부분 아래 실행 위치일 것이다.
http://localhost:8080/swagger-ui.html 
http://localhost:8080/v3/api-docs

 

 

https://springdoc.org/#Introduction

OpenAPI 3 Library for spring-boot

 

결론

Spring REST Docs과 Swagger UI를 같이 사용하고 싶다면 이 library가 간단하다.

 

기존 springfox를 사용했다면 마이그레이션 방법도 있다.

https://springdoc.org/#migrating-from-springfox

OpenAPI 3 Library for spring-boot

 

참고

https://www.baeldung.com/spring-rest-openapi-documentation

Documenting a Spring REST API Using OpenAPI 3.0 | Baeldung