Api-blueprint: Требуется несколько действий одного и того же HTTP-глагола на одном и том же ресурсе (но с другим типом содержимого запроса)

Обновление: я считаю, что могу сделать это, указав только один ответ:

FORMAT: 1A
# multiple posts?
## Try to make two posts [/v1/whatever]
### POST
+ Request JSON (application/json)
        { nil: nil }
+ Request DNS (text/dns)
        whatever
+ Response 204

Однако это не отображается правильно во встроенном режиме (отображается только один тип запроса). Виды предварительного просмотра и документации в редакторе хороши.

@jrep

Это кажется тусклым в нынешнем дизайне (дизайне) пасеки. Я уведомил команду @apiaryio об этой проблеме.

@jrep - это запрос здесь (рядом с ограничением встраивания) для поддержки нескольких ответов?

В таком случае следующее должно быть уже действительным:

FORMAT: 1A

## Try to make two posts [/v1/whatever]

### POST

+ Request JSON (application/json)

        JSON

+ Response 200 (application/json)

        JSON       

+ Request DNS (text/dns)

        whatever

+ Response 200 (text/dns)

        whatever

В вашем примере показано несколько запросов, но только один ответ . Это похоже на мой пример. Да, это синтаксически корректно, но не может выразить то, что нам нужно выразить.

Да: здесь необходимо отображать разные «Ответ 200» для каждого запроса. Тип содержимого ответа соответствует типу содержимого запроса (таким образом, два типа содержимого запроса означают два типа содержимого ответа), но также информация в двух ответах не является точно эквивалентной.

В формате Legacy мы определили один запрос и ответ на него, а затем следующую пару запрос / ответ. Это синтаксическая ошибка в новом формате, и, похоже, нет правильного способа сказать это.

Обновление: Ой, я недостаточно внимательно посмотрел: ваш пример отличается от моего как минимум двумя способами: два ответа и использование именованных запросов. Попробую сейчас.

@jrep

Я не уверен, что вы имеете в виду. Не могли бы вы прислать сюда отрывок из устаревшего чертежа?

Билет на Github не позволяет мне прикреплять текст. Вы можете получить устаревшую схему из https://dev-staging.akamai.com/api/luna/config-dns/blueprint.apib

Понятно

POST /v1/zones/{zone}
> Content-Type: application/json
... some data ...
< 204
< Location: /v1/zones/example.com

POST /v1/zones/{zone}
> Content-Type: text/dns
... some other data ...
< 204
< Location: /v1/zones/example.com

Я думаю, что в принципе нормально выражать это как:

## Zone [/v1/zones/{zone}]

### Create [POST]

+ Request Create with JSON (application/json)

        { ... json data ... }

+ Request Create with DNS (text/dns)

        ... dns data ...

+ Response 204
    + Headers

            Location: /v1/zones/example.com

http://docs.multirequest.apiary.io

Это классический пример согласования содержимого. Создайте ресурс из множества различных представлений, в то время как ответ не имеет тела и просто указывает ОК (и, возможно, ссылку на него).

Аналогом согласования контента для этого будет:

### Retrieve [GET]

+ Request Rerieve JSON representation
    + Headers

            Accept: application/json

+ Response 200 (application/json)

        { ... json data ... }

+ Request Rerieve DNS representation
    + Headers

            Accept: text/dns

+ Response 200 (text/dns)

        ... dns data ...

Я думаю, что один ответ без тела на несколько запросов, которые различаются типом содержимого, но имеют одно и то же значение (создание ресурса), - это хороший дизайн. Однако я хочу снять это ограничение (предупреждение, когда есть несколько ответов с одинаковым статусом и типом контента) с реализацией https://github.com/apiaryio/snowcrash/issues/53

@jrep Эта проблема была устранена в https://github.com/apiaryio/snowcrash/issues/53 (Snow Crash v0.10.0), поэтому я закрываю ее. Прокомментируйте и откройте снова, если необходимо.

Хотя конечная точка может иметь несколько примеров транзакций, как показано в apiaryio / snowcrash # 53, они не очень четко отображаются в Apiary.

Возьмем следующий пример ...

У вас есть /oauth2/authorize , который по спецификации будет обрабатывать различные сценарии (например, получение токена доступа из обновления или создание токена из пароля и т. Д.). Их объединение в одно действие в документации API очень сложно понять читателю, вместо этого пользователю проще иметь несколько конечных точек, таких как «Обновить токен доступа» и «Аутентифицировать пользователя» в боковом меню. Однако это невозможно, потому что вы не можете указать одну и ту же комбинацию метода / URL дважды.

Это яркий пример того, как Спецификация API вынуждает разработчиков использовать определенный подход и, в случаях, подобных описанному выше, не соответствует общим шаблонам проектирования.

Я вижу неправильное выделение синтаксиса - вижу цвет Body :