Swagger 사양을 사용하여 사용할 수 없는 끝점 추가

Composer의 ThingWorx 모델 정의 > 모델링 > 통합 커넥터 > 통합 커넥터 사전 요구 사항 > ODataConnector 또는 SAPODataConnector 사용 > Swagger 사양을 사용하여 사용할 수 없는 끝점 추가

예를 들어, OData 사양에서 다음 EntityType 정의를 고려해 보십시오.

주어진 Document에 PrimaryContent의 추가를 허용하는 끝점이 ODataConnector가 OData 사양을 구문 분석함으로써 생성하는 끝점 목록에 포함되어 있지 않습니다. 일반적으로, EntityType의 NavigationProperty 정의에 대하여 백엔드 시스템에서 지원하는 모든 끝점은 커넥터가 생성하는 목록에 포함되어 있지 않습니다. 따라서 이러한 끝점을 정의하는 Swagger 사양을 만들고 이 사양을 SwaggerJSON 속성의 값으로 JSON 형식에 따라 추가해야 합니다. 자세한 내용은 ODataConnector 또는 SAPODataConnector 사용을 참조하십시오.

위 예에서, 우리는 OData 사양을 살펴봄으로써 다음 사항을 알 수 있습니다.

• 끝점의 경로는 /Documents('{ID}')/PrimaryContent 형식이며, 여기서:

◦ Documents는 Document 엔티티를 포함할 entitySet의 이름입니다.

◦ ID는 Document 인스턴스를 고유하게 식별하는 데 사용되는 Document의 Key입니다. ID 앞뒤의 괄호 {}는 요청 시 자리 표시자를 실제 값으로 바꾸어 제공해야 하는 필수 경로 매개 변수에 대한 자리 표시자라는 것을 나타냅니다.

◦ PrimaryContent는 Document의 NavigationProperty입니다.

• PUT는 PrimaryContent가 ContentItem 유형이기 때문에 Document에 대한 PrimaryContent 업로드를 지원하는 HTTP 작업입니다. ContentItem의 HasStream 속성은 True로 설정되어 있습니다.

• Document의 PrimaryContent로 업로드되어야 하는 파일은 필수 입력 사항이며, 요청의 ContentType는 성공적인 요청 실행을 위해 multipart/form-data이어야 합니다.

• 끝점 실행으로 인한 응답은 다음 중 하나입니다.

◦ 스키마가 ContentItem 정의에 성공적으로 부합하는 JSON 객체.

◦ 올바르지 않은 요청을 나타내는 오류.

Swagger 사양 정의를 만들기 전에 Google Chrome용 Postman 확장 프로그램과 같은 응용 프로그램을 사용하여 끝점에 대해 요청을 실행하는 데 필요한 모든 요구사항을 평가해야 합니다.

Postman에서 요구사항을 평가한 후 Swagger Editor와 같은 도구를 사용하여 끝점에 대한 정의를 만듭니다.

1. 빈 paths 객체로 편집기를 시작합니다.

2. 끝점에 대한 경로와 이 경로를 지원하는 HTTP 작업을 추가합니다. 위 예에서 각각 "/Documents('{ID}')/PrimaryContent"와 put입니다.

3. ID(path 매개 변수)와 File(formData 매개 변수)에 대한 입력 매개 변수 정의를 추가합니다.

4. 끝점에 대한 consumes: [ multipart/form-data ], 및 produces: [ application/json ] 논리를 추가합니다.

5. 끝점이 생성하는 HTTP 상태 코드로 식별된 응답을 추가합니다.

예:

◦ 성공적인 작업(HTTP 상태 코드 200)은 스키마가 ContentItem 정의에 부합하는 JSON 객체를 반환합니다. $ref 속성을 통해 ContentItem 정의에 대한 참조를 나타냅니다.

◦ 잘못된 요청(HTTP 상태 코드 405).

6. ContentItem 정의를 추가합니다. 스키마를 이해하려면 OData 사양에서 ContentItem entityType 정의를 참조하십시오.

7. PUT 작업에 대한 operationId 및 요약을 제공합니다.

8. 이 편집기에서 보고된 오류를 해결하고 필요한 경로, 작업 및 정의를 추가했으면 Swagger 사양을 JSON 파일로 내보냅니다.

9. 내보낸 JSON 파일의 콘텐츠를 복사하고 SwaggerJSON 속성의 값으로 설정합니다.