JHipster는 Java 기반 웹 애플리케이션을 빠르게 개발하기 위한 프레임워크입니다. JHipster를 사용하면 RESTful API를 간편하게 생성할 수 있습니다. 이러한 API를 문서화하여 개발 과정과 유지 보수를 더욱 효율적으로 진행할 수 있습니다. 이번 글에서는 Java JHipster 애플리케이션의 API를 문서화하는 방법을 알아보겠습니다.

1. Swagger를 사용한 자동 API 문서화

Swagger는 API 디자인과 문서화를 위한 강력한 도구입니다. JHipster는 기본적으로 Swagger를 지원하며, 자동으로 API 문서를 생성합니다. Swagger를 사용하여 JHipster API를 문서화하는 방법은 다음과 같습니다.

1. JHipster 애플리케이션에 Swagger 의존성을 추가합니다.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
    <scope>compile</scope>
</dependency>

1. JHipster 애플리케이션의 Application.java 파일에 다음과 같은 @EnableSwagger2 어노테이션을 추가합니다.

@Configuration
@EnableSwagger2
public class Application {
    //...
}

1. JHipster 애플리케이션을 실행한 후 http://localhost:8080/swagger-ui.html에 접속하여 Swagger UI를 확인할 수 있습니다. 여기에서는 API 문서를 자동으로 생성하고 표시합니다.

2. Spring REST Docs를 사용한 수동 API 문서화

Spring REST Docs는 Spring 기반 애플리케이션의 RESTful API를 문서화하기 위한 강력한 도구입니다. Spring REST Docs를 사용하여 JHipster API를 문서화하는 방법은 다음과 같습니다.

1. JHipster 애플리케이션에 Spring REST Docs 의존성을 추가합니다.

<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-core</artifactId>
    <version>2.0.5.RELEASE</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <version>2.0.5.RELEASE</version>
    <scope>test</scope>
</dependency>

1. JHipster 애플리케이션의 테스트 클래스에 다음과 같은 코드를 추가하여 API를 문서화합니다.

//...
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;

@RunWith(SpringRunner.class)
@WebMvcTest(ApiController.class)
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
public class ApiControllerDocumentationTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void testGetApi() throws Exception {
        mockMvc.perform(get("/api"))
            .andExpect(status().isOk())
            .andDo(document("get-api"));
    }
}

1. 테스트를 실행하면 target/generated-snippets 폴더에 API 문서 스니펫이 생성됩니다. 이 스니펫들을 조합하여 API 문서를 생성할 수 있습니다.

결론

Java JHipster 애플리케이션의 API를 문서화하는 방법에 대해 알아보았습니다. Swagger를 사용하여 자동으로 API 문서를 생성하거나 Spring REST Docs를 사용하여 수동으로 문서를 작성할 수 있습니다. 이러한 API 문서화는 개발 과정과 유지 보수를 보다 효율적으로 진행할 수 있도록 도움을 줍니다.

참고 자료:

• JHipster Documentation
• Spring REST Docs Reference Documentation
• Swagger Official Documentation