Добавление недоступных конечных точек с помощью спецификации Swagger

Определение модели ThingWorx в Composer > Моделирование > Соединители интеграции > Необходимые условия для соединителей интеграции > Использование ODataConnector или SAPODataConnector > Добавление недоступных конечных точек с помощью спецификации Swagger

В качестве примера рассмотрим следующие определения EntityType в спецификации OData:

Конечная точка, позволяющая добавить PrimaryContent в данный Document, не включена в список конечных точек, генерируемый модулем ODataConnector при анализе спецификации OData. Вообще любые конечные точки, поддерживаемые внутренней серверной системой для определений NavigationProperty, соответствующих EntityType, не включаются в список, генерируемый соединителем. Поэтому следует создать спецификацию Swagger, определяющую эти конечные точки, и добавить эту спецификацию в формате JSON как значение свойства SwaggerJSON. Дополнительные сведения см. в разделе Использование ODataConnector или SAPODataConnector.

Для приведенного выше примера из спецификации OData можно узнать следующее.

• Путь к конечной точке будет иметь следующий формат: /Documents('{ID}')/PrimaryContent, где

◦ Documents - наименование entitySet, где будут содержаться сущности Document.

◦ ID - это Key для Document, используется для однозначной идентификации экземпляра Document. Скобки {} вокруг ID означают, что это местозаполнитель для обязательного параметра пути, который должен быть указан при создании запроса, когда местозаполнитель будет заменен фактическим значением.

◦ PrimaryContent - это NavigationProperty для Document.

• PUT - это операция HTTP, поддерживающая выгрузку PrimaryContent для Document, поскольку PrimaryContent имеет тип ContentItem. Для ContentItem свойство HasStream имеет значение True.

• Файл, который должен быть выгружен как PrimaryContent для Document, является обязательным входным параметром, а параметр ContentType запроса должен иметь значение multipart/form-data для успешного выполнения запроса.

• Отклик на выполнение операции в конечной точке может быть одним из следующих:

◦ объект JSON, схема которого в точности соответствует определению ContentItem;

◦ сообщение об ошибке, означающее недопустимый запрос.

Прежде чем создавать определение в спецификации Swagger для конечной точки, необходимо удовлетворить все требования к выполнению запроса для этой конечной точки с помощью приложения, такого как расширение Postman для Google Chrome.

После проверки выполнения требований с помощью приложения Postman используйте для создания определения конечной точки такой инструмент, как Редактор Swagger.

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) будет возвращать объект JSON, схема которого соответствует определению ContentItem. Ссылка на определение ContentItem указывается с помощью свойства $ref.

◦ Ошибочный запрос (код статуса HTTP: 405).

6. Добавьте определение ContentItem. Сведения, необходимые для понимания схемы, см. в определении entityType для ContentItem в спецификации OData.

7. Укажите operationId и summary для операции PUT.

8. После разрешения обнаруженных ошибок в редакторе и добавления необходимых путей, операций и определений экспортируйте спецификацию Swagger как файл JSON.

9. Скопируйте содержимое экспортируемого файла JSON и задайте его как значение свойства SwaggerJSON.

Было ли это полезно?