DOCX 파일을 Markdown으로 변환하는 것은 가볍고 버전‑제어에 친화적인 문서를 원하는 개발자들에게 자주 필요한 작업입니다. GroupDocs.Conversion Cloud SDK for Java는 서버 측에서 무거운 작업을 처리하는 강력한 라이브러리를 제공합니다. 이 가이드에서는 Java에서 DOCX를 MD로 변환하는 방법, SDK 설정, 코드를 살펴보기, cURL을 사용한 REST API 활용, 그리고 서식을 유지하기 위한 옵션을 세밀하게 조정하는 방법을 배웁니다.

필수 조건 및 설정

시작하기 전에, 다음 항목이 준비되어 있는지 확인하세요:

  • Java 8 이상이 설치되어 있어야 합니다.
  • IntelliJ IDEA 또는 Eclipse와 같은 IDE.
  • Client Id 및 Client Secret이 포함된 GroupDocs Cloud 계정.
  • 종속성 관리를 위한 Maven.

아래 Maven 종속성을 사용하여 SDK를 프로젝트에 추가하십시오. 또한 최신 JAR 파일을 다운로드 페이지에서 다운로드할 수 있습니다.

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-conversion-cloud</artifactId>
    <version>26.8</version>
</dependency>

SDK가 GroupDocs 클라우드에 인증할 수 있도록 자격 증명을 구성하세요:

Configuration config = new Configuration();
config.setClientId("YOUR_CLIENT_ID");
config.setClientSecret("YOUR_CLIENT_SECRET");

SDK가 준비되면 구현 단계로 넘어갈 수 있습니다. 다음 섹션에서는 DOCX를 MD로 변환하는 데 필요한 각 코드 라인을 자세히 설명합니다.

Java에서 DOCX를 MD로 변환: 단계별 안내

아래는 변환 프로세스에 대한 자세한 단계별 안내입니다. 각 단계는 전체 예제에서 가져온 작은 코드 조각에 해당합니다.

Step 1: API 자격 증명 구성

Configuration 개체를 생성하고 클라이언트 자격 증명을 제공하십시오.

Configuration config = new Configuration();
config.setClientId("YOUR_CLIENT_ID");
config.setClientSecret("YOUR_CLIENT_SECRET");

2단계: Markdown 변환 옵션 정의

소스 DOCX 파일과 대상 MD 파일을 설정하고 서식 보존을 활성화합니다.

MarkdownConvertOptions options = new MarkdownConvertOptions();
options.setFilePath("input.docx");
options.setOutputPath("output.md");
options.setPreserveOriginalFormatting(true);

3단계: Conversion API 초기화

생성한 구성을 사용하여 ConversionApi를 인스턴스화합니다.

ConversionApi conversionApi = new ConversionApi(config);

Step 4: 변환 요청 생성 및 전송

옵션을 ConvertDocumentRequest에 래핑하고 변환 메서드를 호출합니다.

ConvertDocumentRequest request = new ConvertDocumentRequest(options);
ConvertResult result = conversionApi.convertDocument(request);

단계 5: 변환 결과 처리

결과를 확인하고 생성된 Markdown 파일의 경로를 출력합니다.

System.out.println("Conversion completed successfully. Output file: " + result.getPath());

사용된 클래스에 대한 자세한 내용은 API 참조를 확인하십시오.

전체 코드 예제: 서식이 보존된 Markdown 출력

다음 스니펫은 DOCX 파일을 Markdown으로 변환하면서 원본 서식을 유지하는 완전하고 바로 실행 가능한 프로그램을 보여줍니다.

import com.groupdocs.cloud.conversion.api.ConversionApi;
import com.groupdocs.cloud.conversion.client.Configuration;
import com.groupdocs.cloud.conversion.model.MarkdownConvertOptions;
import com.groupdocs.cloud.conversion.model.ConvertResult;
import com.groupdocs.cloud.conversion.model.requests.ConvertDocumentRequest;

public class DocxToMarkdownExample {
    public static void main(String[] args) {
        // Configure API client (replace with your actual credentials)
        Configuration config = new Configuration();
        config.setClientId("YOUR_CLIENT_ID");
        config.setClientSecret("YOUR_CLIENT_SECRET");

// Initialize Conversion API
        ConversionApi conversionApi = new ConversionApi(config);

// Set conversion options for DOCX → Markdown
        MarkdownConvertOptions options = new MarkdownConvertOptions();
        options.setFilePath("input.docx");          // source DOCX file in storage
        options.setOutputPath("output.md");         // target Markdown file in storage
        options.setPreserveOriginalFormatting(true); // keep formatting where possible

// Create request object
        ConvertDocumentRequest request = new ConvertDocumentRequest(options);

try {
            // Execute conversion
            ConvertResult result = conversionApi.convertDocument(request);
            System.out.println("Conversion completed successfully. Output file: " + result.getPath());
        } catch (Exception e) {
            System.err.println("Conversion failed: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

참고: 이 코드 예제는 핵심 기능을 보여줍니다. 프로젝트에 사용하기 전에 파일 경로(input.docx, output.md)를 실제 위치에 맞게 업데이트하고, 모든 필수 종속성이 올바르게 설치되었는지 확인한 뒤 개발 환경에서 충분히 테스트하십시오. 문제가 발생하면 공식 문서를 참조하거나 지원 팀에 문의하십시오.

cURL 및 REST API를 사용한 DOCX를 MD로 변환

순수 HTTP 방식을 선호한다면, 동일한 변환을 cURL 명령으로 수행할 수 있습니다. 아래는 최소한의 워크플로우입니다.

먼저 OAuth2 액세스 토큰을 얻으세요:

curl -X POST "https://api.groupdocs.cloud/v2.0/oauth2/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","grant_type":"client_credentials"}'

응답에 "access_token":"YOUR_ACCESS_TOKEN"가 포함되어 있다고 가정하면, DOCX 파일을 업로드합니다:

curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/input.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary @input.docx

Markdown 변환 요청:

curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "outputPath":"output.md",
           "format":"MD",
           "preserveOriginalFormatting":true,
           "filePath":"input.docx"
         }'

마지막으로, 생성된 Markdown 파일을 다운로드하십시오:

curl -X GET "https://api.groupdocs.cloud/v2.0/storage/file/output.md" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o output.md

전체 매개변수 목록은 공식 API 문서를 확인하십시오.

DOCX에서 MD로 변환 옵션 미세 조정

SDK는 출력물을 제어하기 위해 조정할 수 있는 여러 옵션을 제공합니다.

  • PreserveOriginalFormatting - 헤딩, 리스트, 테이블 및 기타 스타일을 유지합니다.
options.setPreserveOriginalFormatting(true);
  • OutputPath - Markdown 파일이 클라우드 스토리지에 저장될 위치를 정의합니다.
options.setOutputPath("output.md");
  • 맞춤형 마크다운 설정 - MarkdownConvertOptions의 추가 속성을 통해 줄 바꿈, 코드 블록 처리 등을 조정할 수 있습니다 (API 참조를 참조하십시오).

결과 MD 파일에서 원하는 정확한 모양에 맞게 이러한 설정을 실험해 보세요.

DOCX를 MD 변환 시 성능 고려 사항

많은 문서나 큰 파일을 변환할 때는 다음 팁을 기억하세요:

  1. ConversionApi 인스턴스 재사용 - 클라이언트를 한 번만 생성하고 재사용하면 반복적인 인증 오버헤드를 피할 수 있습니다.
  2. 전체 문서를 메모리로 로드하는 대신 파일 스트리밍 - SDK는 대용량 DOCX 파일에 대해 스트리밍을 지원하여 힙 사용량을 줄입니다.
  3. 배치 업로드 - 가능한 경우 여러 DOCX 파일을 하나의 요청으로 업로드하고, 이후 루프에서 변환을 트리거합니다.
  4. 동시성 조정 - 스레드 풀을 사용해 여러 변환을 병렬로 실행하되, API 속도 제한을 모니터링합니다.

이러한 관행을 적용하면 DOCX를 MD 워크플로우로 효율적으로 확장하는 데 도움이 됩니다.

Conclusion

Java에서 DOCX를 MD로 변환하는 것은 GroupDocs.Conversion Cloud SDK for Java를 사용하면 간단합니다. 설정 단계를 따라가고 제공된 코드 예제를 사용하거나 cURL로 REST API를 호출하면 형식을 유지하면서 문서 파이프라인을 자동화할 수 있습니다. 라이선스 옵션을 검토하십시오; SDK는 상업용 라이선스로 제공되며, 평가용 임시 라이선스는 임시 라이선스 페이지에서 얻을 수 있습니다. 오늘 바로 DOCX를 MD로 변환하는 작업을 통합하여 콘텐츠 워크플로를 간소화하십시오.

자주 묻는 질문

Java에서 DOCX를 MD로 변환할 때 서식을 잃지 않으려면 어떻게 해야 하나요?
MarkdownConvertOptions에서 preserveOriginalFormatting을 true로 설정하십시오. SDK는 변환 중에 제목, 표 및 목록을 그대로 유지하도록 시도합니다.

단일 실행에서 여러 DOCX 파일을 MD로 변환할 수 있나요?
예. 파일 목록을 반복하고 동일한 ConversionApi 인스턴스를 재사용하며 각 파일에 대해 convertDocument를 호출하십시오. 이 접근 방식은 오버헤드를 줄이고 배치 처리 속도를 높입니다.

DOCX를 MD로 변환하기 위해 REST API가 요구하는 인증 방법은 무엇인가요?
API는 OAuth2 클라이언트 자격 증명 흐름을 사용합니다. 클라이언트 ID와 비밀을 사용하여 액세스 토큰을 얻은 다음, 이후 모든 호출에 Authorization: Bearer 헤더에 포함합니다.

Markdown 출력 스타일(예: 코드 펜스, 글머리 기호)을 사용자 정의할 수 있나요?
MarkdownConvertOptions 클래스는 Markdown 구문을 세밀하게 조정할 수 있는 여러 속성을 제공합니다. 전체 구성 가능한 옵션 목록은 API reference를 참조하세요.

Read More