Ich habe die Swagger-Benutzeroberfläche verwendet, um meine REST-Webservices anzuzeigen, und sie auf einem Server gehostet.
Auf diesen Dienst von Swagger kann jedoch nur auf einem bestimmten Server zugegriffen werden. Wenn ich offline arbeiten möchte, weiß jemand, wie ich mit der Swagger-Benutzeroberfläche ein statisches PDF erstellen und damit arbeiten kann? Darüber hinaus kann eine PDF-Datei problemlos an Personen weitergegeben werden, die keinen Zugriff auf den Server haben.
Danke vielmals!
Antworten:
Praktische Methode: Verwenden des Browserdrucks / der Vorschau
Ich habe mithilfe von https://github.com/springfox/springfox und https://github.com/RobWin/swagger2markup einen Weg gefunden
Verwendete Swagger 2, um die Dokumentation zu implementieren.
Sie können Ihr REST-Projekt so ändern, dass beim Erstellen des Projekts die erforderlichen statischen Dokumente (HTML, PDF usw.) erstellt werden.
Wenn Sie ein Java Maven-Projekt haben, können Sie das folgende Pom-Snippet verwenden. Es verwendet eine Reihe von Plugins, um eine PDF- und eine HTML-Dokumentation (der REST-Ressourcen des Projekts) zu generieren.
Bitte beachten Sie, dass die Reihenfolge der Ausführung wichtig ist, da die Ausgabe eines Plugins zur Eingabe für das nächste wird:
<plugin>
<groupId>com.github.kongchen</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>3.1.3</version>
<configuration>
<apiSources>
<apiSource>
<springmvc>false</springmvc>
<locations>some.package</locations>
<basePath>/api</basePath>
<info>
<title>Put your REST service's name here</title>
<description>Add some description</description>
<version>v1</version>
</info>
<swaggerDirectory>${project.build.directory}/api</swaggerDirectory>
<attachSwaggerArtifact>true</attachSwaggerArtifact>
</apiSource>
</apiSources>
</configuration>
<executions>
<execution>
<phase>${phase.generate-documentation}</phase>
<!-- fx process-classes phase -->
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>io.github.robwin</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>0.9.3</version>
<configuration>
<inputDirectory>${project.build.directory}/api</inputDirectory>
<outputDirectory>${generated.asciidoc.directory}</outputDirectory>
<!-- specify location to place asciidoc files -->
<markupLanguage>asciidoc</markupLanguage>
</configuration>
<executions>
<execution>
<phase>${phase.generate-documentation}</phase>
<goals>
<goal>process-swagger</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.3</version>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.11</version>
</dependency>
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby-complete</artifactId>
<version>1.7.21</version>
</dependency>
</dependencies>
<configuration>
<sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
<!-- You will need to create an .adoc file. This is the input to this plugin -->
<sourceDocumentName>swagger.adoc</sourceDocumentName>
<attributes>
<doctype>book</doctype>
<toc>left</toc>
<toclevels>2</toclevels>
<generated>${generated.asciidoc.directory}</generated>
<!-- this path is referenced in swagger.adoc file. The given file will simply
point to the previously create adoc files/assemble them. -->
</attributes>
</configuration>
<executions>
<execution>
<id>asciidoc-to-html</id>
<phase>${phase.generate-documentation}</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<outputDirectory>${generated.html.directory}</outputDirectory>
<!-- specify location to place html file -->
</configuration>
</execution>
<execution>
<id>asciidoc-to-pdf</id>
<phase>${phase.generate-documentation}</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<outputDirectory>${generated.pdf.directory}</outputDirectory>
<!-- specify location to place pdf file -->
</configuration>
</execution>
</executions>
</plugin>
Das Asciidoctor-Plugin setzt voraus, dass eine ADOC-Datei vorhanden ist, an der gearbeitet werden kann. Sie können eine erstellen, die einfach diejenigen sammelt, die vom swagger2markup-Plugin erstellt wurden:
include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/definitions.adoc[]
Wenn Sie möchten, dass Ihr generiertes HTML-Dokument Teil Ihrer War-Datei wird, müssen Sie sicherstellen, dass es auf der obersten Ebene vorhanden ist. Statische Dateien im Ordner WEB-INF werden nicht bereitgestellt. Sie können dies im Maven-War-Plugin tun:
<plugin>
<artifactId>maven-war-plugin</artifactId>
<configuration>
<warSourceDirectory>WebContent</warSourceDirectory>
<failOnMissingWebXml>false</failOnMissingWebXml>
<webResources>
<resource>
<directory>${generated.html.directory}</directory>
<!-- Add swagger.pdf to WAR file, so as to make it available as static content. -->
</resource>
<resource>
<directory>${generated.pdf.directory}</directory>
<!-- Add swagger.html to WAR file, so as to make it available as static content. -->
</resource>
</webResources>
</configuration>
</plugin>
Das War-Plugin arbeitet mit der generierten Dokumentation. Daher müssen Sie sicherstellen, dass diese Plugins in einer früheren Phase ausgeführt wurden.
Ich habe eine Website https://www.swdoc.org/ erstellt , die sich speziell mit dem Problem befasst. So automatisiert es die swagger.json -> Asciidoc, Asciidoc -> pdfTransformation, wie in den Antworten vorgeschlagen. Dies hat den Vorteil, dass Sie die Installationsverfahren nicht durchlaufen müssen. Es akzeptiert ein Spezifikationsdokument in Form einer URL oder nur eines rohen JSON. Das Projekt ist in C # geschrieben und die Seite lautet https://github.com/Irdis/SwDoc
BEARBEITEN
Es ist möglicherweise eine gute Idee, Ihre JSON-Spezifikationen hier zu überprüfen : http://editor.swagger.io/, wenn Sie Probleme mit SwDoc haben, z. B. wenn das PDF unvollständig generiert wird.
Kasse https://mrin9.github.io/RapiPdf ein benutzerdefiniertes Element mit zahlreichen Anpassungs- und Lokalisierungsfunktionen.
Haftungsausschluss: Ich bin der Autor dieses Pakets
Für mich war die einfachste Lösung, swagger (v2) in Postman zu importieren und dann zur Webansicht zu wechseln. Dort können Sie die Ansicht "einspaltig" auswählen und mit dem Browser als PDF drucken. Keine automatisierte / integrierte Lösung, aber gut für den einmaligen Gebrauch. Die Papierbreite wird viel besser verarbeitet als beim Drucken in editor2.swagger.io, wo Bildlaufleisten dazu führen, dass Teile des Inhalts ausgeblendet werden.