Wie automatisieren die Dokumentation der REST API (Jersey Umsetzung)

Ich geschrieben habe eine ziemlich umfangreiche REST-API, die mit Java Jersey (und JAXB). Ich habe auch geschrieben, die Dokumentation mit einem Wiki, aber es war ein völlig manueller Prozess, der sehr fehleranfällig, vor allem, wenn wir änderungen vornehmen, die Menschen neigen dazu zu vergessen, ein update der wiki.

Aus schaut sich um, die meisten anderen REST-API ' s sind auch manuell erstellen Ihre Dokumentation. Aber ich Frage mich, ob es vielleicht eine gute Lösung.

Die Art von Dingen, die müssen dokumentiert werden, für jeden Endpunkt sind:

  • Service Name
  • Kategorie
  • URI
  • Parameter
  • Parameter-Typen
  • Antwort-Typen
  • Antwort-Typ Schema (XSD)
  • Probe-Anfragen und-Antworten
  • Art der Anfrage (Get/Put/Post/Delete)
  • Beschreibung
  • Fehlercodes, welche zurückgegeben werden können

Und dann gibt es natürlich noch einige Allgemeine Dinge, die global sind, wie

  • Sicherheit
  • Überblick über REST
  • Fehlerbehandlung
  • Etc

Diese Allgemeinen Dinge sind in Ordnung zu beschreiben, nachdem und müssen nicht automatisiert werden, aber für die web-service-Methoden selbst scheint es höchst wünschenswert, zu automatisieren.

Habe ich gedacht, vielleicht mit Anmerkungen, und schreiben ein kleines Programm, das generiert XML und eine XSLT, die generieren soll die aktuelle Dokumentation in HTML. Macht es mehr Sinn, benutzerdefinierte XDoclet?

  • Enunciate.codehaus.org zieht die Dokumentation aus den Javadocs: es ist open source und funktioniert mit Jersey, so dass Sie vielleicht konnte sehen, dass in so?
  • mögliche Duplikate von RESTful API Dokumentation
  • Ich habe behauptet, für ein paar Jahre jetzt, und es hat einige Macken. Es nicht verarbeitet benutzerdefinierte Typen so gut und ruft völlig verwirrt mit abstrakten dtos. Infact, ich bin über diesen Beitrag gerade jetzt auf der Suche für den Ersatz
Schreibe einen Kommentar