API 문서화 : Swagger, Spring REST Docs

Swagger (Springfox / Springdoc OpenAPI)

• API 문서화 도구
• OpenAPI 표준을 기반으로 동작
• API 자동 문서화 및 실시간 테스트 가능한 UI 제공
• Spring Boot에서 쉽게 설정 가능

샘플 코드 (Springdoc OpenAPI)

// build.gradle 의존성 추가
dependencies {
    implementation 'org.springdoc:springdoc-openapi-ui:1.6.9'
}

// Spring Boot 애플리케이션 클래스
@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

// REST Controller
@RestController
@RequestMapping("/api")
public class ApiController {

    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, World!";
    }
}

• Swagger UI는 http://localhost:8080/swagger-ui.html에서 확인 가능

---

Spring REST Docs

• 테스트 기반 API 문서화 도구
• 실제 API 요청/응답을 기반으로 문서 자동 생성
• UI는 제공하지 않으며, AsciiDoc이나 Markdown 형식으로 문서화

샘플 코드 (Spring REST Docs)

// build.gradle 의존성 추가
dependencies {
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

// 테스트 클래스
@RunWith(SpringRunner.class)
@WebMvcTest(ApiController.class)
@AutoConfigureRestDocs(outputDir = "target/snippets")
public class ApiControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void sayHello() throws Exception {
        mockMvc.perform(get("/api/hello"))
                .andExpect(status().isOk())
                .andDo(document("hello",
                        preprocessResponse(prettyPrint())));
    }
}

// build.gradle 플러그인 추가
plugins {
    id 'org.asciidoctor.jvm.convert' version '3.3.2'
}

// 리소스 폴더에 문서화될 API 요청/응답 샘플 파일 추가

• 문서는 target/generated-snippets 폴더에 생성되어 AsciiDoc 또는 HTML로 변환 가능

---

 Swagger & Spring REST Docs

항목	Swagger (Springdoc OpenAPI)	Spring REST Docs
문서화 방식	자동화된 UI 기반 문서화	테스트 기반 문서화 (실제 요청/응답을 통해 생성)
UI 제공	제공 (Swagger UI)	제공하지 않음
설정 용이성	설정 간단, 몇 가지 의존성만 추가하면 바로 사용 가능	설정이 다소 복잡, 테스트 코드와의 결합 필요
문서화 정확도	코드 주석 및 애너테이션을 기반으로 한 자동 생성	테스트 케이스 기반으로 실제 동작하는 문서화 가능
지원 형식	JSON, YAML	AsciiDoc, Markdown
기능성	실시간 API 테스트 가능, API 탐색 용이	UI가 없어 실시간 테스트는 불가능, 대신 신뢰도 높은 문서화 가능
장점	- 빠르고 직관적인 API 문서화 - UI 제공으로 테스트 및 탐색 용이	- 실제 요청/응답을 기반으로 한 정확한 문서화 - 테스트 코드와 일관성 있음
단점	- 자동화된 문서화가 부족한 경우가 있음 - 문서 내용이 코드와 완벽하게 일치하지 않을 수 있음	- UI 미제공으로 실시간 테스트 불가 - 설정 및 사용에 시간이 더 걸림