Genera PDF dalla documentazione dell'API Swagger

93

Ho utilizzato l'interfaccia utente di Swagger per visualizzare i miei servizi web REST e l'ho ospitato su un server.

Tuttavia, è possibile accedere a questo servizio di Swagger solo su un determinato server. Se voglio lavorare offline, qualcuno sa come posso creare un PDF statico utilizzando l'interfaccia utente di Swagger e lavorarci? Inoltre un PDF è facile da condividere con persone che non hanno accesso al server.

Grazie molto!

pdf  swagger-ui 
— Aman Mohammed
fonte

Risposte:

39

Modo pratico: utilizzo della stampa / anteprima del browser

  1. Nascondi il riquadro dell'editor
  2. Anteprima di stampa (ho usato Firefox, anche gli altri andavano bene)
  3. Modificare l'impostazione della pagina e stampare in pdf

inserisci qui la descrizione dell'immagine

— Osify
fonte
Semplice! La documentazione esce abbastanza bene.
— ShaTin
1
Puoi anche scegliere tra due progetti di documentazione purché ci siano due servizi Swagger: editor.swagger.io (nuovo) e editor2.swagger.io (precedente)!
— naXa
L'interfaccia utente HTML bcos swagger efficace ma con perdite ha più schede, per i parametri di un metodo POST / PUT è necessario scegliere tra la scheda del modello e la scheda del valore di esempio, quindi nella versione stampata in PDF una di queste è nascosta per sempre :(
— chrisinmtown
Questo non ha funzionato per me. Ogni endpoint verrebbe tagliato con la fine della pagina (indipendentemente dalla configurazione della pagina che ho usato). La pagina successiva inizierà quindi nella parte superiore del successivo blocco Endpoint. Forse qualcosa è cambiato da quando è stata scritta questa risposta.
— killa-byte
Vedo ancora che è praticabile, potrebbe essere necessario adattare il margine. Prova da editor.swagger.io
— Osify
33

Ho trovato un modo usando https://github.com/springfox/springfox e https://github.com/RobWin/swagger2markup

Ho utilizzato Swagger 2 per implementare la documentazione.

— Aman Mohammed
fonte
ciao, sto anche cercando di generare documentazione offline usando swagger.Sei in grado di generare documentazione swagger ??
— Sunil Rk
Sì, ho utilizzato i progetti di esempio e ho integrato il mio codice del servizio web in essi e sono stato in grado di generare la documentazione.
— Aman Mohammed
1
Puoi dirmi in breve, come posso integrare il mio servizio web negli esempi che hai menzionato sopra.
— Sunil Rk
Il progetto swagger2markup richiede un input JSON dell'API REST. Se scarichi quel progetto gradle e modifichi il file swagger.json in quello con i dettagli dell'API, quindi esegui il metodo JUnit Swagger2MarkupConverterTest: testSwagger2HtmlConversion, dovrebbe generare l'HTML per te nella cartella build / docs / generated / asciidocAsString del progetto. Quindi in altre parole ci sono 2 cose. 1) Innanzitutto genera il formato JSON per la tua API REST utilizzando Swagger Editor. 2) Utilizzando questo formato JSON, puoi utilizzare il progetto swagger2markup per produrre documentazione HTML autonoma dell'API
— Aman Mohammed,
22

Puoi modificare il tuo progetto REST, in modo da produrre i documenti statici necessari (html, pdf, ecc.) Al momento della costruzione del progetto.

Se hai un progetto Java Maven puoi usare lo snippet pom qui sotto. Utilizza una serie di plugin per generare un pdf e una documentazione html (delle risorse REST del progetto).

  1. rest-api -> swagger.json: swagger-maven-plugin
  2. swagger.json -> Asciidoc: swagger2markup-maven-plugin
  3. Asciidoc -> PDF: asciidoctor-maven-plugin

Tieni presente che l'ordine di esecuzione è importante, poiché l'output di un plug-in diventa l'input del successivo:

<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>

Il plugin asciidoctor presuppone l'esistenza di un file .adoc su cui lavorare. Puoi crearne uno che raccolga semplicemente quelli che sono stati creati dal plugin swagger2markup:

include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/definitions.adoc[]

Se vuoi che il tuo documento html generato diventi parte del tuo file war devi assicurarti che sia presente al livello superiore - i file statici nella cartella WEB-INF non verranno serviti. Puoi farlo nel plugin maven-war:

<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>

Il plugin war funziona sulla documentazione generata - in quanto tale, devi assicurarti che quei plugin siano stati eseguiti in una fase precedente.

— Hervian
fonte
Ciao @Hervian. Bella risposta. Finora potrei usare la tua risposta. Ho due classi con lo stesso nome ma in pacchetti diversi. Tuttavia, swagger.json contiene la definizione solo per uno di essi. L'altro manca
— edmond il
@Hervian Ho ricevuto errori fino a quando non ho fatto quanto segue 1) ho creato il file src / main / asciidoc / swagger.adoc con il contenuto dall'alto. 2) ha aggiunto queste proprietà al POM: <phase.generate-documentation> process-classes </phase.generate-documentation> <generated.asciidoc.directory> $ {project.build.directory} / api-gen </ generated. asciidoc.directory> Quindi esegui "mvn install" e non vedo errori mvn o plugin, ma solo il file overview.adoc ha dei contenuti; i file definizioni.adoc e paths.adoc rimangono vuoti. Pls consiglia.
— chrisinmtown
15

Ho creato un sito web https://www.swdoc.org/ che affronta specificamente il problema. Quindi automatizza la swagger.json -> Asciidoc, Asciidoc -> pdftrasformazione come suggerito nelle risposte. Il vantaggio di questo è che non è necessario eseguire le procedure di installazione. Accetta un documento delle specifiche sotto forma di URL o solo un json grezzo. Il progetto è scritto in C # e la sua pagina è https://github.com/Irdis/SwDoc

MODIFICARE

Potrebbe essere una buona idea convalidare le tue specifiche json qui: http://editor.swagger.io/ se hai problemi con SwDoc, come il pdf generato incompleto.

— Irdis
fonte
3
grazie, sì è piuttosto carino, lo uso per i miei progetti di lavoro. Sto pensando di scrivere del codice per supportare openapi 3.0 nel mio tempo libero.
— Irdis
2
Tutta la gloria agli autori degli strumenti su cui si basa, ofc
— Irdis
@Irdis ho provato a utilizzare il collegamento. Consente di analizzare il documento Swagger 2.0 ma il documento che sto fornendo è di Open API 3.0 e non è in grado di generare il documento.
— hellowahab
Ho provato Swagger 3+ - funziona bene, mostra html grezzo per i commenti però ...
— Sasha Bond
Questo è un grande strumento! Se hai problemi come i miei (come il pdf generato incompleto), incolla il tuo json qui: editor.swagger.io per essere convalidato automaticamente, risolvi i problemi e sarai pronto a tornare allo strumento swdoc e generarlo correttamente questa volta.
— Thales Valias
9

Checkout https://mrin9.github.io/RapiPdf un elemento personalizzato con molte funzionalità di personalizzazione e localizzazione.

Disclaimer: sono l'autore di questo pacchetto

— Mrinmoy
fonte
2
appena testato ma non ricevo risposta dopo aver fatto clic su "Genera PDF" con le specifiche di prova (petstore)?
— imehl
1
@imehl Funziona bene quando mi ho provato su mac / chrome, mac / firefox, mac / safari e windows / chrome. Funziona solo su browser web che supportano componenti web come Chrome, Firefox e Safari. Se i problemi persistono, accedi a Github github.com/mrin9/RapiPdf
— Mrinmoy
@Mrinmoy Ho avuto lo stesso problema di imehl, ha aperto una nuova scheda ma si è chiusa immediatamente (ubuntu 18.04 + firefox / chrome entrambi lo stesso risultato). Poi l'ho fatto su Windows e ha funzionato a meraviglia. Grazie per questo strumento, è fantastico.
— Dabux
3
@Dabux non è mai stato testato su Ubuntu, ma so che c'è una situazione in cui le persone affrontano lo stesso problema che hai spiegato, ed è quando hai un blocco attivo come blocco o blocco popup sul browser
— Mrinmoy
@Mrinmoy hai ragione, avevo un blocco degli annunci, è stato per questo, non per il sistema operativo.
— Dabux
1

Per me la soluzione più semplice era importare swagger (v2) in Postman e poi andare alla visualizzazione web. Qui puoi scegliere la visualizzazione "singola colonna" e utilizzare il browser per stampare in pdf. Non è una soluzione automatizzata / integrata ma va bene per uso singolo. Gestisce la larghezza della carta molto meglio della stampa da editor2.swagger.io, dove le barre di scorrimento nascondono parti del contenuto.

— Simon
fonte
1
ho provato a usarlo ma la stampa tramite pagina web aggiunge diversi collegamenti e anche altre informazioni.
— hellowahab
Sì, avrei dovuto menzionarlo. Non è stato un problema per il mio utilizzo.
— Simon
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.