Coze 플러그인이 OpenAPI 3.1을 가져오지 못하는데, 이 문제는 특히 미리 만들어진 인터페이스 정의를 붙여넣을 때 흔히 발생합니다. 많은 사람들이 한두 필드만 바꾸는 것이라고 생각하지만, 사실 Coze의 플러그인 파싱은 스키마 구조에 더 민감하며, 가장 잘 걸리는 부분은 응답 본체 유형입니다.
커뮤니티에서 흔히 보고하는 오류 내용은 매우 일관적입니다: "인터페이스가 사용 불가능하다"가 아니라 "인터페이스 문서가 Coze가 기대하는 형태가 아니다"라는 내용입니다. 예를 들어, 일부 3.1 작성 방법, 빈 응답 스키마, 지나치게 복잡한 조인트 타입은 가져오기 과정에서 직접 차단됩니다.
왜 OpenAPI 3.1이 문제에 더 취약한가
3.1은 더 표현력이 풍부하기 때문에, 플러그인 임포터가 모든 고급 글쓰기를 사용 가능한 입력으로 취급하지 않을 수 있습니다. 사용자에게는 문서가 명세를 살펴봅니다; 수입업체의 경우, 가장 단순한 구조 일부만 인식할 수 있습니다. 공개 이슈에서는 "Response Body는 객체 유형만 지원한다" 같은 상황에서 막혔는데, 이는 플러그인 가져오기가 반환 구조에 대해 느슨하지 않다는 것을 보여줍니다.
피트 위를 적게 밟고 싶다면 먼저 이 세 가지를 하세요
- 먼저 OpenAPI를 더 단순한 3.0.x 스타일로 수렴시키세요.
- 응답자 몸체를 가능한 한 표준화된 '객체'로 유지하고, 복잡하고 중첩되거나 빈 스키마를 바로 쓰지 마세요.
- 필수 필드를 단순화하고, body를 요청한 뒤, 최소 실행 가능한 버전으로 본문을 반환한 후 점진적으로 추가하세요.
지역사회에서 이를 더 실용적으로 다루는 방법
많은 사람들이 결국 Coze를 '고치기' 않고, 다시 OpenAPI 파일을 정리하고 보수적으로 바꾸는 경우가 많습니다. 그 이유는 현실적입니다: Coze 플러그인 가져오기의 목표는 모든 OpenAPI 문법을 흡수하는 것이 아니라, 인터페이스를 안정적으로 호출 가능한 플러그인으로 전환하는 것입니다. 문서를 더 많이 랩할수록 가져오기 실패 가능성이 높아집니다.
임포트 과정에서 막히면, 인터페이스 자체가 사용 불가능하다고 먼저 의심하기보다는 오류가 구조체, 타입, 필드 이름을 가리키는지 확인하는 것이 좋습니다. 많은 경우, 스키마가 너무 복잡해서 수입업체가 추측하고 싶지 않기 때문입니다.
한 문장 결론
Coze 플러그인이 OpenAPI 3.1을 가져오지 못한 이유는 주로 잘못된 인터페이스 때문이 아니라, 문서 구조가 너무 복잡하고 반환 본문 타입이 기준에 미치지 못했기 때문입니다. 스키마를 단순화하자면, 성공률은 보통 훨씬 높습니다.
