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
Du musst angemeldet sein, um einen Kommentar abzugeben.
Swagger ist eine schöne option. Es ist ein Projekt auf GitHub, hat die Maven-integration und viele weitere Optionen zu halten Sie es flexibel.
Integration guide: https://github.com/swagger-api/swagger-core/wiki
Mehr Informationen: http://swagger.io/
Leider Darrel Antwort ist technisch korrekt, aber ist hocus-pocus in der realen Welt. Es basiert auf dem ideal, dass nur einige Stimmen auf und auch wenn man sehr vorsichtig ist es, die Chancen, dass aus irgendeinem Grund außerhalb Ihrer Kontrolle, können Sie nicht exakt übereinstimmen.
Selbst wenn Sie könnten, andere Entwickler, die vielleicht benutzen deine API kann nicht kümmern oder wissen, die details von Rest-Muster... denken Sie Daran, dass der Zeitpunkt der Erstellung der API ist es leicht für andere, es zu benutzen und eine gute Dokumentation ist ein muss.
Achim ' s Punkt über das WADL ist gut jedoch. Weil es existiert, wir sollten in der Lage sein zu erstellen, die ein grundlegendes Instrument für die Dokumentation der API.
Einige Leute haben diesen Weg gegangen, und ein XSL-stylesheet entwickelt wurde, um zu tun, die Transformation:
https://wadl.dev.java.net/
Stackoverflow.com
mit einem Roboter, die Sie brauchen würde, intime Kenntnisse über die Struktur und die zu erwartende Nutzung der Website. Sie würden nicht "erkunden Sie von einem root-URL", noch erwarten, dass der media-Typ "text/html" bieten viel helfen. Sie würde am Ende zu erforschen, es von hand zu erstellen, die genau die Art von Karte eine gute API-Dokumentation bietet.Obwohl ich bin nicht sicher, es wird ganz auf Ihre Bedürfnisse, nehmen Sie einen Blick auf aussprechen. Es scheint wie eine gute Dokumentations-generator für verschiedene web-services-Architekturen.
BEARBEITEN Behauptet ist verfügbar unter github Regenschirm
vielleicht haben Sie Interesse in Jersey ' s Fähigkeit bieten so genannte WADL Beschreibung für alle veröffentlichten Ressourcen im XML-format (Laufzeit automatisch generiert aus Anmerkungen). Sollte dies enthält bereits, was Sie brauchen für eine grundlegende Dokumentation. Weiter könnten Sie in der Lage sein, um zusätzliche JavaDoc, aber das erfordert etwas mehr Konfiguration.
Bitte mal hier:
https://jersey.java.net/documentation/latest/wadl.html
Darrel ' s Antwort ist genau richtig. Die Art der Beschreibung muss nicht gegeben werden, um Kunden von einer REST-API, weil es führen wird, der client-Entwickler zu koppeln, die Implementierung der client auf die aktuelle Implementierung des service. Dies ist, was REST ist und hypermedia-constraint-Ziele zu vermeiden.
Könnten Sie noch entwickeln einer API, ist beschrieben, dass die Art und Weise, aber Sie sollten sich bewusst sein, dass das resultierende system wird nicht Umsetzung der REST-Architekturstil und wird daher nicht die Eigenschaften (insb. evolvability) garantiert RUHE.
Ihre Schnittstelle vielleicht noch eine bessere Lösung, als die RPC zum Beispiel. Aber bewusst sein, was es ist, dass Sie bauen.
Jan
Finden Sie vielleicht rest-tool nützlich.
Es folgt sprachneutral-Ansatz zu schreiben, Spezifikationen, mock-Implementierung und automatisierten unit-Tests für RESTful APIs.
Können Sie es verwenden, nur für die mit der Dokumentation der APIs, aber diese Angabe kann sofort verwendet werden, um die Qualität gewährleisten, die Umsetzung der realen Dienstleistungen.
Wenn Ihre Leistungen noch nicht vollständig umgesetzt, sondern zum Beispiel, wird durch eine web-frontend-Applikation, rest-tool bietet sofortige Spott auf der Grundlage der service-Beschreibung. Inhalt der schema-Validierung (JSON-schema) kann einfach Hinzugefügt werden, die neben der Dokumentation auch, wie bei den unit-tests.
Ich hasse es der überbringer schlechter Nachrichten, aber wenn Sie das Bedürfnis verspüren, zu dokumentieren, die Dinge, die Sie aufgelistet ist, dann hast du wahrscheinlich nicht schaffen, eine REST-Schnittstelle.
REST-Schnittstellen sind dokumentiert durch die Identifizierung einer einzigen root-URL und dann durch die Beschreibung der Medien Art der Darstellung, die zurückgegeben wird, die URL und alle Medien-Typen, die aufgerufen werden kann über die links in dieser Darstellung.
Welche Medien-Typen verwenden Sie?
Auch einen link zu RFC2616 in Ihren docs. Das sollte erklären, jeder Verbraucher-wie interagieren Sie mit Ihrem service.