Как я перестал волноваться и стал отдавать метаданные restful API

[quozd]

Чем не устроило встроенное решение ApiExplorer?

[Nonick]

Оно как раз и используется для получения метаданных.

[quozd]

Как то у вас слишком все переусложнено, по сравнению с

public ActionResult Index()
{
    var apiExplorer = GlobalConfiguration.Configuration.Services.GetApiExplorer();
    return View(new ApiDocumentationModel(apiExplorer));
}

View можно скастомизировать по вкусу.

[Nonick]

Тут всё тоже самое, только код из конструктора ApiDocumentationModel, для наглядности помещён прямо в контроллер.

[Shaddix]

Мне кажется, или вы завелосипедили Web API help page?

[Nonick]

Да, но с возможностью сделать свой фронтенд. WebApi Help Pagе делает страницы с документацией для людей, а при публикации метаданных в json, можно сгенерировать клиент к API.

[Shaddix]

Ну в WebAPI очень даже можно сделать свой фронтэнд — там весь UI в обычных разоровских вьюшках, меняй не хочу.

js-клиент, это, безусловно, плюс, надо будет посмотреть детальнее. В посте про это мельком. Детали реализации это хорошо, но собственно на функционале и отличиях от встроенного механизма акцента не хватает, мне кажется.

[Nonick]

Спасибо за наводку, идея с OPTIONS очень нравится.

[skiedr]

Есть еще протокол XHTTP. С его помощью можно легко создавать версионные API и отдавать метаданные.

[Sardar]

Для питона есть Sphinx. Он не только строит документацию, включая в нее API доку из исходников, но и может запускать тесты из docstring'ов. Или просто запускать тесты во время билда, кому как нравиться. Главное, что можно не ограничиваться только API докой, можно писать полноценную документацию. Пример и сорцы. Просто пример, как это может быть чуть более кратко.

[wersoo]

А почему не использовать WSDL 2.0? Или XML настолько немодный?

[Fragster]

Есть ли Reflection для JS? Объясню, откуда этот вопрос: для PHP я написал я помощью Reflection генератор WSDLей, которые кушает 1ска, причем ты ему скармливаешь имена функций, а дальше он через этот самый Reflection все зависимые классы разворачивает через Reflection и phpdoc. Хотелось бы реализовать что-то подобное для node.js.

[Nonick]

Не совсем понял вопрос, но скорее всего вам подойдёт вот это — github.com/mashery/iodocs

[Fragster]

тут, опять же, надо самому делать описание. Задача же — сгенерить описание по коду, желательно на лету. Например:

$ws = new WS1c('http://fragster.ru/multithread', 'fragster');

$ws->methods[] = new ReflectionFunction('resultsExchange');
$ws->methods[] = new ReflectionFunction('newResults');
$ws->methods[] = new ReflectionFunction('appendTestResult');
$ws->methods[] = new ReflectionFunction('test');

header("Content-Type: text/xml;");
if (isset($_REQUEST['wsdl'])) {
    echo $ws->getWSDL();
} else {
    echo  $ws->handleRequest($xml);
}

и на выходе получаем fragster.ru/perfomanceTest/ws.php?wsdl

[Nonick]

В JS чтобы получить информацию о содержании объекта, каких-то специальных механизмов не нужно, всегда можно сделать
for (member in object) ...
Если этого недостаточно, то всегда можно сделать AST из исходников и провести static analysis.

[shergin]

Это все круто, но сам классический REST плох тем, что смешивает транспортный уровень (HTTP) и прикладной уровень (собственно ваше API, основанное на обмене объектами). Т.е. например если вы потом захотите завернуть ваше REST API в ВебСокеты, то это будет не слишком легко.

[Sardar]

У вас есть внутренний API и его аналог, опубликованный через REST. Вам ничего не мешает внутренний API также опубликовать через SOAP или вебсокеты. Другое дело, что с вебсокетами вы меняете сам принцип запрос-ответ на потоковое вещание, что выглядит как минимум странно.

[Sardar]

Промахнулся по ссылке «ответить», просьба игнориривать.

[AndryX]

Мы сначала генерировали документацию по результатам тестов, а сейчас зафиксировали её в сервисе apiary.io. (PHP)