Документирование параметров POST с помощью WADL - PullRequest
Новая
       22

Документирование параметров POST с помощью WADL

5 голосов
/ 21 мая 2010

Глядя на текущую версию предложения WADL , я не мог понять, как задокументировать параметры запроса POST (с кодировкой application/x-www-form-urlencoded).

Я видел что-то подобное в дикой природе: 

<resource path="/path1">
<!-- default is mediaType="application/x-www-form-urlencoded" -->
    <method name="POST">
        <request>
            <name="param1" style="query"/>
        </request>
    </method>
</resource>

Однако для <param style="query">, используемого в качестве потомка <request>, спецификация описывает его как :

Указывает URI-запрос параметр представлены в соответствии с правилами для тип носителя компонента запроса определяется атрибутом queryType.

Бит "запрос URI" отбросил меня, поскольку, мне кажется, он предполагает добавление параметров в URI вместо включения в тело.

С другой стороны, для <param style="query">, используемого в качестве потомка <representation>, спецификация имеет:

Определяет компонент представление в виде пары имя-значение отформатирован в соответствии с правилами тип носителя. Обычно используется с тип носителя 'application / x-www-form-urlencoded' или 'Многочастному / форм-данных'.

Нужно ли использовать элемент <representation> для явного документирования параметров, которые будут отправлены в кодировке как часть тела POST? 

<resource path="/path1">
    <method name="POST">
        <request>
            <representation mediaType="application/x-www-form-urlencoded">
                <name="param1" style="query"/>
            </representation>
        </request>
    </method>
</resource>

Это похоже на излишество. Я предполагаю, что я смогу использовать первый, хотя в спецификации упоминается "URI запрос".

1 Ответ

2 голосов
/ 31 мая 2010

Теперь я вижу, что на самом деле я должен использовать последнюю форму. Даже если это выглядит излишне просто для документирования некоторых параметров POST, лучше явно задокументировать тот факт, что параметры являются частью представления body ==.

Стороннее редактирование

Последний, вероятно, означает это 

<resource path="/path1">
    <method name="POST">
        <request>
            <representation mediaType="application/x-www-form-urlencoded">
                <name="param1" style="query"/>
            </representation>
        </request>
    </method>
</resource>
...