Как я могу заставить Azure API Management документировать тело запроса при использовании Swagger?

Мы используем Swagger 2.0 для документирования наших веб-API .Net, которые мы размещаем в Azure за Azure API Management. У меня проблемы с получением документации с подробным описанием сложных объектов, которые публикуются как часть тела. Azure не показывает никаких подробностей об объекте, оставляя меня самому документировать их. Ниже приведен файл json, который я импортировал в службу управления API Azure.

{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "Hotel Search",
        "description": "The seodecnvewjkl"
    },
    "basePath": "/v1",
    "consumes": [
        "application/xml",
        "application/json"
    ],
    "produces": [
        "application/xml",
        "application/json"
    ],
    "schemes": [
        "http",
        "https"
    ],
    "paths": {
        "/hotels/search": {
            "post": {
                "operationId": "searchCommand",
                "description": "Searches for hotels",
                "parameters": [
                    {
                        "name": "hotelSearchRq",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/HotelSearchRq"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "schema": {
                            "title": "HotelSearchRs",
                            "$ref": "#/definitions/HotelSearchRs"
                        }
                    },
                    "400": {
                        "description": "Bad Request"
                    },
                    "404": {
                        "description": "Unauthorised"
                    }
                }
            },
            "get": {
                "operationId": "searchQuery",
                "parameters": [
                    {
                        "name": "CorrelationId",
                        "in": "query",
                        "type": "string"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response"
                    }
                }
            }
        }
    },
    "definitions": {
        "StayDetail": {
            "type": "object",
            "properties": {
                "NumberOfGuests": {
                    "type": "integer"
                },
                "CheckinDate": {
                    "type": "string",
                    "format": "date",
                    "description": "the date that the stay starts from"
                }
            }
        },
        "HotelSearchCriteria": {
            "type": "object",
            "properties": {
                "MaximumResults": {
                    "type": "integer",
                    "format": "int64"
                },
                "StayDetails": {
                    "$ref": "#/definitions/StayDetail"
                }
            }
        },
        "HotelSearchRq": {
            "type": "object",
            "properties": {
                "CustomerTransactionIdentifier": {
                    "type": "string",
                    "description": "The customers transaction identifier"
                },
                "search_criteria": {
                    "$ref": "#/definitions/HotelSearchCriteria"
                }
            }
        },
        "HotelSearchRs": {
            "type": "object"
        }
    }
}

Операционный экран управления API Azure

Может ли кто-нибудь помочь мне с тем, как я могу автоматически документировать тело из документации swagger?


person John Sharland    schedule 25.11.2015    source источник
comment
Я знаю, что над этой функцией недавно работали. Позвольте мне попытаться предоставить вам дополнительную информацию о том, когда она будет доступна.   -  person Darrel Miller    schedule 28.11.2015
comment
Спасибо за это, Даррел, ты хоть представляешь, когда он станет доступен? Просто это нам очень поможет, потому что у нас потенциально будет 40+ API, которые нам понадобятся для раздельного документирования всех тел запросов и ответов.   -  person John Sharland    schedule 30.11.2015
comment
Извините, у меня нет графика для этого. Особенностью, о которой я слышал, была возможность проверять ответы на основе схемы. Если для вас важен импорт схемы и примеров ответов для отображения в документации, могу ли я предложить добавить предложение на сайт обратной связи feedback.azure.com/forums/248703-api-management Спасибо.   -  person Darrel Miller    schedule 30.11.2015
comment
Еще один комментарий, и не стесняйтесь принимать его или оставлять. Мой опыт создания API-интерфейсов привел меня к выводу, что документирование структур, специфичных для конкретного URL / запроса / ответа, приводит к значительному дублированию. Определение словаря для вашей проблемной области, допустимых структур и отношений между их структурами - это более точный способ описания вашего домена, который затем может быть повторно использован во многих ресурсах / API. например github.com/darrelmiller/conference-talk/blob/master/   -  person Darrel Miller    schedule 30.11.2015
comment
Прискорбно видеть, что в 2017 году эта проблема все еще не решена.   -  person MickyD    schedule 24.01.2017
comment
@DarrelMiller Не совсем уверен, куда вы идете со своим последним комментарием, но факт остается фактом: члены нашей корпорации, а также внешние подрядчики и аффилированные лица не могут использовать наш API, потому что шлюз API, в данном случае APIM, не упоминает, какие параметры и / или тело требуется. Когда речь идет о шлюзе API, разговоры о дублировании неуместны. Если людей беспокоит дублирование, они не будут использовать шлюз API в первую очередь, а просто будут использовать базовый REST API и обратиться к документации Swagger.   -  person MickyD    schedule 24.01.2017
comment
@DarrelMiller ... Понятно, что APIM намерен задокументировать импортированные API, но, похоже, еще не полностью. Если бы целью не было дублирование, мы бы вообще не увидели никакой документации по API на порталах APIM Publisher и DEV, что явно не так.   -  person MickyD    schedule 24.01.2017
comment
@MickyD Моя личная точка зрения и точка зрения APIM разные. Я полностью понимаю желание подробно описать область поверхности API. Насколько мне известно, теперь это полностью реализовано в Azure API Management. Если у вас что-то не работает, сообщите нам, и мы рассмотрим ситуацию.   -  person Darrel Miller    schedule 24.01.2017
comment
@DarrelMiller Спасибо, не могли бы вы исследовать, пожалуйста, в соответствии с моим комментарием ниже - мы используем вложенный $refs в соответствии с примером OP   -  person MickyD    schedule 25.01.2017


Ответы (1)


В настоящее время информация тела запроса и ответа из документа Swagger не отображается в документации портала разработчика.

Это уже не так. Образцы и схема отображаются на портале разработчика.

person Darrel Miller    schedule 27.11.2015
comment
@MickyD Это работает для всех, кроме двух сценариев, о которых я знаю. Если у вас нет производит / потребляет, он не будет отображаться, или если у вас есть вложенные $ refs в ваши схемы. - person Darrel Miller; 24.01.2017
comment
У меня есть Produits + Consumes, а также вложенные $refs - точно так же, как в примере OP - person MickyD; 25.01.2017
comment
@MickyD К сожалению, не заметил вложенных $ refs в приведенном выше примере. Это очень важно в моем списке дел. - person Darrel Miller; 26.01.2017
comment
@DarrelMiller. Я использую в своем swagger и «производит / потребляет», и не, используя $ refs, но параметры запроса по-прежнему не отображаются в определении запроса-операции API. Вкладка multipart / form-data пуста. - person Juraj Paulo; 13.06.2017
comment
@JurajPaulo Можете ли вы опубликовать пример документа о проблеме в новом вопросе и отметить меня, и я изучу проблему? - person Darrel Miller; 13.06.2017