Я использую clojure для создания REST API. Как автоматически сгенерировать документацию REST?
Я пишу сервис clojure rest (с помощью ring, compojure и liberator) и хотел бы автоматически генерировать документацию по API для всех моих REST API. Это очень утомительно, чтобы создать его вручную. Есть ли способ использовать аннотации или что-то вроде этого? Будет здорово, если я смогу сделать это с помощью lein gen-rest-docs.
2 ответа
Свойство " Uniform Interfaces" стиля архитектуры REST не поддерживает документацию для отдельных конечных точек. В REST вы полагаетесь на самоописательные сообщения и гиперссылки для управления приложением.
Хотя я вижу, что вам нужно документировать свой API, я рекомендую сосредоточиться на документировании того, как типы мультимедиа применяются к вашему домену, и общих предположениях при реализации. Обычно это касается авторизации, SLA. Если вы правильно используете типы мультимедиа и гиперссылки, то для отдельных ресурсов больше не нужно много документации.
Если это не вариант, знайте, что у вас есть архитектура RPC. В этом случае может помочь ринг-чванство и подобные решения.
Дайте ринг-чванцу попробовать. Имеет параметры compojure, fnhouse и Pedestal