Apicurio-studio: 사양 문서 전체에서 구성 요소 개체에 대한 참조 지원

사용 사례

이것이 해결될 주요 사용 사례는 사용자에게 데이터 유형 정의를 단일 파일(또는 파일 세트)로 중앙 집중화할 수 있는 기능을 제공하는 것입니다. 그런 다음 이러한 데이터 유형은 중앙 위치를 참조하여 여러 API 정의에서 활용할 수 있습니다.

고려 사항

외부 참조를 지원하려면 여러 가지 개선 사항이 필요합니다. 다음은 특별한 순서가 없는 목록입니다.

• 데이터 모델 라이브러리(현재 oai-ts-core 이지만 곧 apicurio-data-models )는 플러그형 참조 확인자를 지원하도록 향상되어야 합니다. 현재 이러한 라이브러리는 내부 참조만 확인할 수 있습니다. 대신 라이브러리 소비자 는 외부 참조를 성공적으로 확인할 수 있도록 사용자 지정 참조 확인자를 제공할 수 있어야 합니다.

• Apicurio Studio는 데이터 유형 설계에 중점을 둔 편집기와 함께 "데이터 유형 전용" 스타일 리소스를 지원해야 합니다. 이를 통해 API 디자인과 독립적으로 데이터 유형을 생성/관리하기 위한 보다 구체적인 워크플로가 가능합니다.

• API 디자인 편집기에서 유형을 설정할 때 도구는 외부 리소스에서 유형을 선택하는 방법이 필요합니다. 선택을 위해 이러한 외부 유형을 사용자에게 가장 잘 표시하는 방법을 고려해야 합니다. API 디자인이 다른 리소스/파일을 "가져오기"하여 UI가 사용자의 선택 범위를 좁혀 현명하게 표시할 수 있는 방법이 필요할 수 있습니다. 편집기는 일종의 선택 UI 컨트롤에서 사용 가능한 데이터 유형을 표시하기 위해 외부 리소스를 가져오고 구문 분석해야 합니다.

• 진행 중인 데이터 유형 리소스를 API 디자인에서 외부 참조의 소스로 사용할 수 있는지 여부를 결정해야 할 수도 있습니다. 즉, API 디자인에서 "스냅샷" 데이터 유형을 참조할 수 있어야 합니까? 또는 데이터 유형 리소스가 외부 참조의 소스로 사용되기 전에 "최종"이 되어야 합니다. 전자의 경우 종속성도 완료될 때까지 API 디자인을 "완료"할 수 없습니다. 참고: 이 전체 개념을 사용하려면 Apicurio에서 최종 리소스를 구현해야 합니다!

• Apicurio 리소스를 참조할 때 $ref 형식이 무엇인지 결정해야 합니다. 현재 모든 API 디자인(또는 이론적인 데이터 유형 리소스)에는 고유 ID가 있지만 생성 시 생성되는 불투명 ID입니다. 해당 ID는 현재 해결 목적으로 리소스를 식별하는 유일한 고유한 방법입니다. 리소스가 완료되면(이러한 개념을 지원하는 경우) 리소스에 보다 인간 친화적인 식별자를 부여한 다음 $ref URI에서 사용할 수 있습니다. 우리가 무엇을 하든 API 레지스트리(또 다른 미래 기능)에 리소스를 게시할 때 API 디자인의 모든 $references는 API 레지스트리에서 합리적인 방식으로 확인할 수 있어야 합니다.

다음은 $ref 허용되는 값에 대한 몇 가지 정보입니다.

$ref의 값은 URI이지만 네트워크 로케이터가 아니라 식별자일 뿐입니다. 이는 스키마가 해당 URI에서 액세스할 수 있어야 하는 것은 아니지만 액세스할 수 있음을 의미합니다. 기본적으로 외부 스키마 URI를 처리하는 방법은 유효성 검사기 구현에 달려 있지만 유효성 검사기가 $ref 값에 표시된 네트워크 리소스를 가져올 것이라고 가정해서는 안 됩니다.

참조에 대한 자세한 내용은 OpenAPI 사양 및 JSON 참조 RFC 에서 찾을 수 있습니다.

Apicurio 내의 다른 사양에서 DataTypes에 대한 참조 구현의 우선 순위를 지정할 수 있습니까(처음에는 외부 참조가 아니라)?

내가 이것을 말하는 이유는 Swagger의 사소하지 않은 사용에 일부 상호 참조 기능이 필요하기 때문입니다. 예를 들어, 우리는 데이터 유형(예: 주소, 사람 등)을 공유하는 다양한 서비스를 구현하고 있으며 이러한 모든 사양에 Apicurio를 사용하려고 합니다. 그러나 현재로서는 상호 참조를 사용할 수 없기 때문에 할 수 없습니다.

Apicurio 내의 다른 사양에서 DataTypes에 대한 참조 구현의 우선 순위를 지정할 수 있습니까(처음에는 외부 참조가 아니라)?

내가 이것을 말하는 이유는 Swagger의 사소하지 않은 사용에 일부 상호 참조 기능이 필요하기 때문입니다. 예를 들어, 우리는 데이터 유형(예: 주소, 사람 등)을 공유하는 다양한 서비스를 구현하고 있으며 이러한 모든 사양에 Apicurio를 사용하려고 합니다. 그러나 현재로서는 상호 참조를 사용할 수 없기 때문에 할 수 없습니다.

동의합니다. 이것은 우리를 킬러 앱 영역으로 이끌 것입니다.

@jsenko 일단 레지스트리 impl을 마무리하고 나면 커뮤니티에서 분명한 우선 순위를 갖게 되는 것 같습니다. :)

직장에서 apicurio를 사용하고 참고 자료를 사용하면 다른 팀에 매우 유용할 것입니다.

시간이 조금 걸리긴 했지만 외부 참조는 다음 릴리스(내일 완료될 예정)인 베타 2.46부터 공식적으로 지원될 예정입니다. 다른 Apicurio Studio 문서에서 현재 문서로 데이터 유형 및 응답을 가져오는 새로운 UI가 있습니다. 또한 외부 http/s 및 Apicurio 내부 참조 확인을 지원하도록 유효성 검사가 업데이트되었습니다. 이것은 문서 전반에 걸친 참조에 대한 성숙한 지원을 위한 좋은 첫 번째 단계가 되어야 합니다.