Как автоматизировать документацию API REST (Реализация Джерси) [закрытый]

Question

Как автоматизировать документацию API REST (Реализация Джерси) [закрытый]

Можно воссоздать функциональность виртуальных функций в C++ с помощью указателей функции в качестве членов класса и статических функций как реализации, или с помощью указателя на функции членства и функции членства для реализаций. Существуют только письменные преимущества между этими двумя методами... на самом деле, вызовы виртуальной функции являются просто письменным удобством сами. На самом деле наследование является просто письменным удобством..., оно может все быть реализовано, не используя функции языка для наследования.:)

ниже непротестированное дерьмо, вероятно, содержащий ошибки код, но надо надеяться демонстрирует идею.

, например,

class Foo
{
protected:
 void(*)(Foo*) MyFunc;
public:
 Foo() { MyFunc = 0; }
 void ReplciatedVirtualFunctionCall()
 {
  MyFunc(*this);
 }
...
};

class Bar : public Foo
{
private:
 static void impl1(Foo* f)
 {
  ...
 }
public:
 Bar() { MyFunc = impl1; }
...
};

class Baz : public Foo
{
private:
 static void impl2(Foo* f)
 {
  ...
 }
public:
 Baz() { MyFunc = impl2; }
...
};

62

java rest documentation automation jersey

задан Cœur 25 July 2018 в 02:05

4 ответа

Другие вопросы по тегам:

java rest documentation automation jersey

Похожие вопросы:

score -1 · Answer 1

Ненавижу быть носителем плохих новостей, но если вы чувствуете необходимость задокументировать то, что вы перечислили, то вы, вероятно, не создавали интерфейс REST.

Интерфейсы REST документируются путем идентификации одного корневого URL-адреса, а затем путем описания типа мультимедиа представления, которое возвращается из этого URL-адреса, и всех типов мультимедиа, к которым можно получить доступ через ссылки в этом представлении.

Какие типы мультимедиа вы используете?

Кроме того, поместите ссылку на RFC2616 в свои документы. Это должно объяснить любому потребителю, как взаимодействовать с вашим сервисом.

score 8 · Answer 2

вас может заинтересовать способность Джерси предоставлять так называемое WADL описание для всех опубликованных ресурсов в формате XML во время выполнения (создается автоматически из аннотаций). Он уже должен содержать то, что вам нужно для базовой документации. В дальнейшем вы можете добавить дополнительный JavaDoc, хотя для этого потребуется дополнительная настройка.

Пожалуйста, посмотрите здесь: https://jersey.java.net/documentation/latest/wadl.html

score 3 · Answer 3

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

Вы все еще можете разработать API, который описан таким образом, но вы должны знать, что полученная система не будет реализовывать архитектурный стиль REST и, следовательно, не будет обладать свойствами (в частности, эволюционируемостью), гарантированными REST.

Ваш интерфейс все еще может быть лучшим решением, чем, например, RPC. Но отдавайте себе отчет в том, что именно вы создаете.

Jan

score 21 · Answer 4

К сожалению, ответ Даррела технически правильный, но в реальном мире это фокус-покус. Он основан на идеале, с которым согласны только некоторые, и даже если вы были очень осторожны с ним, велика вероятность, что по какой-то причине, не зависящей от вас, вы не сможете точно соответствовать.

Даже если бы вы могли, другие разработчики, которым, возможно, придется использовать ваш API, могут не заботиться или знать детали шаблонов RESTful ... Помните, что цель создания API - облегчить его использование другими и хорошо документация обязательна.

Точка зрения Ахима о WADL, тем не менее, хороша. Поскольку он существует, мы должны иметь возможность создать базовый инструмент для создания документации API.

Некоторые люди пошли по этому пути, и для этого была разработана таблица стилей XSL: https://wadl.dev.java.net/