Ich würde gerne eine Möglichkeit finden, eine nette REST-API-Dokumentation aus Java-Code (WADL oder HTML) zu generieren - basierend auf JAXB, JAX-RS-Annotationen und Java-Doc-Kommentaren (kein Doclet bitte).
Hier ist meine Projektumgebung
Probieren Sie aussprechen .
Enunciate ist eine Engine zur drastischen Verbesserung Ihrer Java Web Service API. Es ist einfach. Sie entwickeln Ihre Web-Service-API mithilfe von Standard-Java-Technologien und hängen Enunciate an Ihren Build-Prozess an. Plötzlich verfügt Ihr Web-Service-API über einige ziemlich beeindruckende Funktionen:
- Vollständige HTML-Dokumentation Ihrer Dienste, die Sie von Ihren JavaDocs erhalten haben.
- Clientseitige Bibliotheken (z. B. Java, .NET, iPhone, Ruby, Flex, AJAX, GWT usw.) für Entwickler, die mit Ihrer API interagieren möchten.
- Schnittstellendefinitionsdokumente (z. B. WSDL, WADL, XML-Schema, usw.)
- usw.
Alternativ zu Enunciate könnten Sie auch MireDot in Erwägung ziehen. Es ist aus einem Werkzeug entstanden, das wir in unserer eigenen Firma verwenden und es ist kostenlos für Open-Source-Projekte. Es tut genau das, was du beschreibst: es kombiniert Jaxrs-Annotationen und existierende Javadoc-Kommentare, um eine Rest-API zu erzeugen. Es funktioniert wie ein Maven-Plugin, das Sie einfach zu Ihrem Projekt hinzufügen müssen. Jaxb-Annotationen werden zum Zeitpunkt des Schreibens noch nicht unterstützt, aber das Tool wird gerade entwickelt und wir wählen die Features aus, die basierend auf Vorschlägen / Anfragen / Feedback implementiert werden sollen.
Mit den Java-Compiler-APIs können Sie Code schreiben, der die Java-Quelle analysiert und Ihre eigene Verarbeitung durchführt.
Hier ist ein Lehrartikel , der Informationen zum Parsen von Anmerkungen enthält.
Ich schätze, dass Sie die Rohdaten, die Sie benötigen, mit diesen APIs extrahieren können. Dies wird jedoch syntaktische Fakten liefern - die REST-URLs und Aktionen und Parameter, ein Benutzer würde auch von einer zusätzlichen Erklärung profitieren, die der Dienstautor in Java Doc bereitstellen könnte (sollte?).
Die vollständige Lösung könnte sein, sowohl Annotation als auch Java Doc zu analysieren und die beiden zu kombinieren.