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

Question

Я редактирую документацию Apiary по проекту, над которым я работаю, и должен указать, что параметр для одного из моих вызовов API является строкой datetime. Кажется, что Пасека захлебывается от форматирования этого параметра, поэтому мне интересно, какой будет предлагаемый подход для документирования этого параметра в Пасеке.

Чтобы продемонстрировать, я взял стандартные документы по умолчанию из Пасека и модифицировал Choice документации принять объект DATETIME, как так:

## Choice [/questions/{question_id}/choices/{choice_id}/{datetime}] 

+ Parameters 
    + question_id: 1 (required, number) - ID of the Question in form of an integer 
    + choice_id: 1 (required, number) - ID of the Choice in form of an integer 
    + datetime: 2015-05-05T12:30:00 (optional, date) - The date/time (ISO8601 format) associated with this choice 

Конечным результатом этого является следующий текст:

datetime 
05-05T12:30:00 (optional, date) - The date/time (ISO8601 format) that all returned events should be greater than or equal to Example: 2015. 

Это явно неправильно, даже запишите значение примера. Тире (-) является особым персонажем, который вызывает здесь горе. Каков рекомендуемый подход для этого?

Answer 1

Вы должны be able to use backticks в качестве последовательности экранирования. Также обратите внимание, что there is no such type as date. Вы должны использовать string:

+ datetime: `2015-05-05T12:30:00` (optional, string) - The date/time (ISO8601 format) associated with this choice