내가 만든 API를 널리 알리기 - Spring REST Docs 가이드편

선물하기 시스템을 재개발하며 기존 Wiki API 문서를 개선하기 위해 Spring REST Docs를 도입했다. Swagger는 빠르게 동적 문서를 만들 수 있지만 상세한 설명을 추가할수록 애노테이션이 운영 코드에 들어갈 수 있고, Spring REST Docs는 테스트를 작성해야 문서 스니펫을 생성해 API 변경을 검증할 수 있다는 점을 선택 이유로 들었다. 테스트 결과를 AsciiDoc과 Asciidoctor로 HTML 문서화하고, Spring REST Docs API specification Integration으로 OpenAPI YAML도 생성해 Swagger UI와 Postman에서 활용하도록 구성했다. 문서화 도구는 각자의 장단점과 팀의 작성 부담을 비교해 선택하되, 테스트 기반 문서화는 API에 대한 신뢰를 높이는 방법이라고 설명한다.

• Spring REST Docs는 테스트가 통과해야 문서 스니펫을 생성하므로 API 변경을 테스트 과정에서 확인할 수 있다.
• Asciidoctor는 테스트에서 생성한 스니펫과 AsciiDoc 파일을 조합해 HTML 문서로 렌더링한다.
• 사용자 정의 스니펫을 적용할 때는 Spring REST Docs 버전에 맞는 템플릿 경로를 확인해야 한다.
• Swagger UI에서 API를 직접 호출하려면 CORS·CSRF·FrameOption 설정을 개발 환경에 한정해 조정한다.
• Spring REST Docs와 Swagger 중 무엇을 선택할지는 운영 코드 변경, 문서 작성 비용, 테스트 필요성을 함께 고려한다.