Можно ли использовать API-интерфейс WSO2 API Manager 1.8.0 Publisher «недокументированный» для импорта определений API через Swagger json?

Question

В моей автоматизированной среде сборки/развертывания Я хочу использовать WSO2 API издателя Добавить вызов API (см https://docs.wso2.com/display/AM180/Publisher+APIs)

http://<host>:<port>/publisher/site/blocks/item-add/ajax/add.jag 

добавить API-интерфейсы/обновления, снабжая мои файлы определений Кураж JSON API, сгенерированных из Java Spring @ Классы RestController с аннотациями Swagger 1.2.

Похоже, что эта возможность в настоящее время не поддерживается (см. Запрос ожидающих функций https://wso2.org/jira/browse/APIMANAGER-3255 - Внесите API-интерфейс издателя, чтобы импортировать определение swagger с использованием файла или URL-адреса).

Однако есть недокументированные API, который поддерживает эту который я успешно опробованы:

https://host:port/publisher/site/blocks/item-design/ajax/add.jag? ... &swagger={<API SWAGGER DEFINITION GOES HERE>} 

Безопасно ли использовать этот API? Просьба уточнить ответ с пояснениями/предпосылкой/будущими планами.

Где «безопасный» определяется как: Является ли хорошей практикой использование недокументированного API? Если да, то почему это не документировано? Если нет, почему бы и нет, каковы риски его использования, каковы побочные эффекты, будущие обновления WSO2 могут привести к поломке пользователей этого API? Почему этот API предоставляет больше функциональности, чем документированный?

Пример:

https://localhost:9443/publisher/site/blocks/item-design/ajax/add.jag? 
name=FOOAPI& 
version=1.0.0& 
provider=admin& 
context=/home& 
action=design& 
visibility=public& 
swagger= 
{ 
    "apiVersion":"1.0.0", 
    "swaggerVersion":"1.2", 
    "apis":[ 
    { 
     "file": 
     { 
     "apiVersion":"1.0.0", 
     "basePath":"http://localhost:8280/home/1.0.0", 
     "resourcePath":"/rest", 
     "swaggerVersion":"1.2", 
     "apis":[ 
      { 
      "path":"/rest/v2/clients", 
      "operations":[ 
       { 
       "method":"GET", 
       "nickname":"getCustomers", 
       "responseClass":"api_clients", 
       "parameters":[ 
        { 
        "name":"firstResult", 
        "paramType":"query", 
        "description":"desc", 
        "dataType":"int", 
        "allowMultiple":false 
        }, 
        { 
        "name":"resultsPerPage", 
        "paramType":"query", 
        "description":"desc", 
        "dataType":"int", 
        "allowMultiple":false 
        } 
       ], 
       "summary":"The clients REST service end point returns a set of clients", 
       "notes":"The clients REST service end point returns a set of clients", 
       "errorResponses":[ 
        { 
        "code":200, 
        "reason":"Clients found" 
        }, 
        { 
        "code":400, 
        "reason":"Invalid input, returns message body of Errors" 
        }, 
        { 
        "code":500, 
        "reason":"A database error has occurred" 
        } 
       ], 
       "produces":[ 
        "application/xml", 
        "application/json" 
       ], 
       "consumes":[ 
        "*/*", 
        "application/xml" 
       ] 
       } 
     ] 
     }, 
     "description":"", 
     "path":"/rest" 
    } 
    ] 
} 

Answer 1

Ответ на ваш вопрос, зависит от вашего определения "безопасной". Моя информация заключается в том, что документально подтвержденные API-интерфейсы будут стабильными с будущей версией 1.9 и, безусловно, будут изменены плановой версией 2.0.