Ich habe die Aufgabe, den besten Weg für eine große API, entwickelt mit Jaxrs, für Dritte zu dokumentieren. Der Code ist derzeit mit Javadoc gut dokumentiert. Meine Frage ist es, anhand meiner bisherigen Forschung den besten Ansatz zu finden und zu überprüfen, dass wir den richtigen Weg eingeschlagen haben. Daher suche ich nach Input, Kommentaren oder zusätzlichen Frameworks, um sie zu betrachten. Ich bin mir sicher, dass dies ein häufiger Anwendungsfall ist und andere ähnliche Probleme haben werden und wirklich jeden Input von anderen schätzen werden, die Erfahrung mit Prahlerei und Dokumentation haben.Automatische Generierung von Ruhe-Endpunkten mit Swagger für Java
Wir haben Anforderungen, die:
- Wir haben keine große Anzahl von Annotationen den Code unübersichtlich.
- Wir können Rückgabetypen wie verschachtelte Objekte und ihre richtige JSON-Struktur dokumentieren.
- Wir können Header, Links und Meta-Informationen angeben (was bedeutet, dass wir Swagger 2.0 anstelle von 1.2 brauchen)
- Wir möchten Zeit und Kosten minimieren, wo immer möglich, aber trotzdem eine gute Dokumentation behalten.
- Arbeiten mit JDK 8.
ich die folgenden Rahmenbedingungen betrachtet haben, aber jeder scheint, dass einige große Nachteile haben sie entweder schwer machen mit (für dieses Projekt) zu arbeiten, oder dass ich vielleicht Mißverständnis .
Die Swagger JAXRS doclet: Link
Dieses Maven Plugin arbeitet bei der Erstellung und ist in der Lage uns mit angemessener Dokumentation über die bestehenden javadoc Kommentare basieren. However, it does not support Swagger 2.0, die Einschränkungen bei der Beschreibung von Überschriften in Antworten, die für unseren Anwendungsfall wichtig sind, setzen können. Es ist in der Lage, die restlichen Dienste ohne die @ Api- oder @ ApiOperation-Annotationen, die das swagger maven-Plugin benötigt, abzurufen. Dies zu aktualisieren, um mit swagger 2.0 zu arbeiten, kann eine wesentliche Aufgabe sein.
Das Swagger Maven Plugin: Link
Das Plugin erstellt die Prahlerei Dokumentation zum Zeitpunkt der Erstellung auf Basis von Annotationen statt Kommentare. Dies würde erfordern, dass wir das gesamte Projekt durchgehen und Anmerkungen mit @Api und @ApiOperation machen. Es kann sein, dass einige Anmerkungen nur für Basisklassen verfügbar sind, aber für Beschreibungen oder Titel von Endpunkten müssen wir Details in den Annotationen selbst hinzufügen. Viele dieser Annotationen scheinen doppelt zu sein, da wir zum Beispiel bereits @Get oder @Post haben, aber auch noch @ApiOperation hinzufügen und die Parameter beschreiben müssen, die bereits in javadoc beschrieben sind. Der Untergang ist, dass dies Zeit braucht, und wird auch in sehr unübersichtlichem Code resultieren.
Swagger Kern: Link
Swagger Kern zur Laufzeit arbeitet, was bedeutet, dass wir nicht in der Lage sind Kommentare aus dem bestehenden javadoc aus abzustreifen. Es ist leicht erweiterbar, genauso wie das Swagger Maven Plugin, und wir könnten unseren eigenen Leser oder Regeln hinzufügen, um Links und Metainformationen hinzuzufügen (oder unsere eigenen existierenden Annotationen zu verwenden). Der Nachteil ist, dass Beschreibungen für jede Methode von irgendwo kommen müssen, also müssen diese in (noch mehr) Annotationen hinzugefügt werden, die beim Hinzufügen von neuem Code wahrscheinlich vergessen werden.
enunciate: Link
enunciate für uns nicht funktioniert, da wir einen ähnlichen Rahmen auf .NET zu verwenden, müssen in der Lage, und es unterstützt auch keine JDK 8 (noch) nicht.
Meine Schlussfolgerungen bisher
Die Prahlerei jaxrs doclet war in der Nähe, alles zu tun, die wir bisher wollen. Das Hauptproblem ist das Fehlen von Swagger 2.0. Wir müssen in der Lage sein, Swagger-Versionen entsprechend zu aktualisieren, da andere Projekte, die zusammen dokumentiert werden (verschiedene Sprachen), ausreichen werden. Das zweitbeste für uns ist das Swagger Maven Plugin, da es sich um einen eigenen Runner handelt, da es Zeit für Builds ist, sollte es irgendwie möglich sein, Zugang zu den vorhandenen Javadoc Kommentaren zu bekommen und diese zum produzierten Swagger hinzuzufügen - wir werden wahrscheinlich davonkommen einige Anmerkungen sind in Basisklassen und ziehen den Rest (zB Beschreibungen) aus Kommentaren mit unserem benutzerdefinierten Leser. Schließlich dient der prahlerische Kern nicht wirklich unseren Bedürfnissen, da wir viele weitere Anmerkungen benötigen würden, die existierendes Javadoc duplizieren.
Mit der unbekannten Zeit benötigt, um das Swagger Doclet zu aktualisieren, um Swagger 2.0 zu unterstützen, stehe ich auf das Swagger Maven Plugin mit einem benutzerdefinierten Leser (irgendwelche Tipps, wie man javadoc Kommentare von dort lesen wäre nützlich!). Gibt es einen Rahmen oder ein Detail, das ich übersehen habe, was meine Schlussfolgerung ungenau macht?
Wenn Sie Spring verwenden, ist Springfox (http://springfox.github.io/springfox/docs/current) auch eine Option. – Sampada
Danke - leider ist es nicht Frühling, aber eine Abstimmung für Sie, wie auch immer die nächste Person, die diese Frage betrachtet, sein könnte. – ThePerson