Ich habe die Swagger-Benutzeroberfläche verwendet, um meine REST - Webservices anzuzeigen und auf einem Server zu hosten.
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 statische PDF erstellen und damit arbeiten kann? Darüber hinaus ist ein PDF für Benutzer, die keinen Zugriff auf den Server haben, leicht zugänglich.
Danke vielmals!
Ich habe einen Weg gefunden, mit https://github.com/springfox/springfox und https://github.com/RobWin/swagger2markup
Verwendete Swagger 2 zum Implementieren der Dokumentation.
Sie können Ihr REST - Projekt ändern, um die erforderlichen statischen Dokumente (HTML, PDF usw.) beim Erstellen des Projekts zu erstellen.
Wenn Sie ein Java-Maven-Projekt haben, können Sie das unten abgebildete Pom-Snippet verwenden. Es verwendet eine Reihe von Plugins, um eine PDF- und eine HTML-Dokumentation (der Ressourcen des Projekts REST) zu erstellen.
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 geht davon aus, dass eine .adoc-Datei vorhanden ist. 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 Kriegsdatei 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 Kriegs-Plugin arbeitet mit der generierten Dokumentation. Daher müssen Sie sicherstellen, dass diese Plugins in einer früheren Phase ausgeführt wurden.
Während die Lösung von Amaan Mohammed so aussieht, als würde sie funktionieren, gibt es einen einfacheren Weg, dies zu tun. Werfen Sie einen Blick auf swagger2markup-cli .
Ich habe eine Website erstellt https://www.swdoc.org/ , die speziell auf das Problem eingeht. So automatisiert es die swagger.json -> Asciidoc, Asciidoc -> pdf
-Transformation, wie in den Antworten vorgeschlagen. Dies hat den Vorteil, dass Sie die Installationsprozeduren nicht durchlaufen müssen. Es akzeptiert ein Spezifikationsdokument in Form einer URL oder nur eines rohen Json. Die Projektseite ist https://github.com/Irdis/SwDoc
Für mich war es am einfachsten, Swagger (v2) in Postman zu importieren und dann zur Webansicht zu wechseln. Dort können Sie die Ansicht "einspaltig" auswählen und den Browser zum Drucken in PDF verwenden. Keine automatisierte/integrierte Lösung, aber für den einmaligen Gebrauch geeignet. Es verarbeitet Papierbreiten viel besser als das Drucken aus editor2.swagger.io, wo Bildlaufleisten dazu führen, dass Teile des Inhalts ausgeblendet werden.