Документирование запроса Полезная нагрузка в apiblueprint

Question

У меня есть много конечных точек API для документирования, и полезная нагрузка запросов POST и PUT может быть сложной. Я документирую их с помощью apiblueprint. Мне очень нравится, как apiblueprint позволяет мне документировать параметры URI. Он выглядит хорошо и позволяет предоставить читателю всю необходимую им информацию, такую ​​как (обязательный, String или Integer, список вариантов/значений и пример).

Когда мы смотрим раздел «Запрос», однако я не вижу, как обеспечить тот же уровень первоначальной документации. Секции запроса, которые я видел, просто предоставляют примерный запрос.

Скажем, мы имеем дело с простой полезной нагрузкой, которая требует всего целого имени с именем id, который требуется. В настоящее время мой запрос раздел будет выглядеть следующим образом,

Headers

Content-Type: применение/JSON

тела

{ "ID": "123"}

Предполагается, что тело запроса должно быть разреженным? Каков наилучший способ передать моим пользователям все ограничения/требования для моих полезных нагрузок REST?

Answer 1

Если я вас правильно понимаю, вы ищете способ докумен ваш запрос paramters (заголовки, тело и т.д.)

Если это так, то используйте раздел схемы и написать хорошо документированный JSON-Schema

, например, вы тока простой запрос будет выглядеть следующим образом:

Request 

    + Headers 

     Content-Type: application/json 

    + Schema 

     { 
      "type":"object", 
      "properties":{ 
       "id": { 
        "type" : "string", 
        "required": true 
       } 
      } 
     } 

    + Body 

    {"id":"123"}