Хороший способ генерировать документацию для моего API на основе сервлетов?

Question

Кто-нибудь знает хороший инструмент или стратегию для генерации внешней документации для коллекции Java-сервлетов?Конечно, я мог бы использовать мой любимый текстовый редактор для создания независимого документа.Но это может быть более вероятным, если документация находится в исходном коде.К сожалению, проблема немного неструктурирована.Каждый сервлет является классом Java, но это конец официальной структуры.Внутри метода doGet сервлета он использует некоторый набор параметров, закодированных в URL, совершенно неструктурированным способом и производит какой-то вывод, скажем, веб-страницу или объект JSON.

Javadoc неплохо документируетсам код, но я хочу документировать API, видимый клиентами моего сервиса.

В стиле javadoc я мог бы представить размещение документации по классу и, возможно, определить некоторую аннотацию для размещения локальных переменных метода doGet.которые представляют параметры.Но мне все еще нужна специализированная обработка - я не хочу, чтобы javadoc генерировал по умолчанию.

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

Answer 1

Я бы сказал, что вы должны добавить пару свойств к своим сервлетам - добавить свойство parameters и свойство response_details (или что-то подобное).Затем потребуйте это как часть вашей подписи сервлета;они могут содержать строки в каком-то популярном текстовом формате (Markdown, ReST?), который описывает ввод и вывод этого сервлета.

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

Вы можете добавить больше структуры к тому, что фактически требуется в этих свойствах, если хотите - например, parameters может потребоваться, чтобы он был Map<String,String> или что-то в этом роде.как это.Это все зависит от вас.