Ich war auf der Suche nach einem javadoc-ähnlichen REST-API-Dokumentationstool . Ich habe bereits meine Ruhe-Controller in Javadoc dokumentiert und ich denke, es wäre schön, einfach eine API-Dokumentation daraus für die Front-End-Entwickler zu erstellen.
Ich denke, es gibt noch kein Werkzeug. Hat jemand Ideen, wie er diese Aufgabe erfüllen kann? Ich habe über das klassische javadoc-Tool nachgedacht und eine spring / rest-spezifische Logik hinzugefügt. Aber ich bin mir noch nicht sicher, ob ich auch ein spezielles Markup benötige oder was Fallstricke sein könnten. Am Ende möchte ich ein Tool haben, das in den Maven Site Lifecycle integriert werden kann , aber das sollte nicht schwer zu erreichen sein.
Es mag schwierig sein, mit der Vererbung umzugehen: Ich benutze sie sehr oft in REST-Ressourcen, aber für den Leser ist Vererbung nichts, was sie interessieren sollte. Daher müssen Subcontroller die Supercontroller-Methoden irgendwie integrieren, aber auch in der Lage sein, eine aussagekräftige Dokumentation im Kontext des eigentlichen Controllers zu erstellen. Ich bin mir nicht sicher, ob Spring mir erlaubt, Methoden von Super-Controllern zu überschreiben, aber trotzdem seine Annotationen bewertet.
Ich würde mich über Hinweise zu verwandten Projekten, bereits vorhandenen Tools oder einfach über Ihre Erfahrung mit dem javadoc-Tool freuen!
Wenn du das selbst machen wolltest, könntest du es so angehen:
@Path -Anmerkungen name -Attribut {customerId} ) in etwas Bedeutungsvolles für Dokumentationszwecke zu mappen - vielleicht durch Lesen des zugehörigen Javadoc. Der Annotation Reader muss keine Änderungen an den vorhandenen Annotationen vornehmen, daher sollte es einfach sein, eine Liste der regulären Ausdrücke des Endpoints zu erstellen. In Kombination mit den Javadocs sollten Sie in der Lage sein, ein nützliches Werkzeug zu erstellen. Ich würde es sicherlich nützlich finden, und vielleicht auch andere.
Ich weiß Enunciate , was ziemlich gut mit Jersey / CXF funktioniert - aber ich weiß nicht, ob es mit SpringMVC.