Hasilkan PDF dari dokumentasi API Swagger

Saya telah menggunakan UI Swagger untuk menampilkan layanan web REST saya dan menghostingnya di server.

Namun layanan Swagger ini hanya dapat diakses di server tertentu. Jika saya ingin bekerja secara offline, apakah ada yang tahu bagaimana saya dapat membuat PDF statis menggunakan UI Swagger dan bekerja dengannya? Selain itu, PDF mudah dibagikan dengan orang yang tidak memiliki akses ke server.

Terimakasih banyak!

Cara praktis: Menggunakan Pencetakan / Pratinjau Browser

1. Sembunyikan panel editor
2. Pratinjau Cetak (Saya menggunakan firefox, yang lain juga baik-baik saja)
3. Ubah pengaturan halamannya dan cetak ke pdf

Saya menemukan cara menggunakan https://github.com/springfox/springfox dan https://github.com/RobWin/swagger2markup

Menggunakan Swagger 2 untuk mengimplementasikan dokumentasi.

Anda dapat memodifikasi proyek REST Anda, untuk menghasilkan dokumen statis yang diperlukan (html, pdf dll) saat membangun proyek.

Jika Anda memiliki proyek Java Maven, Anda dapat menggunakan potongan pom di bawah ini. Ini menggunakan serangkaian plugin untuk menghasilkan pdf dan dokumentasi html (sumber daya REST proyek).

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

Perlu diketahui bahwa urutan eksekusi penting, karena keluaran dari satu plugin, menjadi masukan untuk yang berikutnya:

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

Plugin asciidoctor mengasumsikan keberadaan file .adoc untuk dikerjakan. Anda dapat membuatnya yang hanya mengumpulkan yang dibuat oleh plugin swagger2markup:

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

Jika Anda ingin dokumen html yang Anda buat menjadi bagian dari file perang Anda, Anda harus memastikan bahwa itu ada di tingkat atas - file statis di folder WEB-INF tidak akan disajikan. Anda dapat melakukan ini di maven-war-plugin:

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

Plugin perang berfungsi pada dokumentasi yang dihasilkan - dengan demikian, Anda harus memastikan bahwa plugin tersebut telah dijalankan pada fase sebelumnya.

Saya membuat situs web https://www.swdoc.org/ yang secara khusus membahas masalah tersebut. Jadi itu mengotomatiskan swagger.json -> Asciidoc, Asciidoc -> pdftransformasi seperti yang disarankan dalam jawaban. Manfaatnya adalah Anda tidak perlu melalui prosedur instalasi. Ini menerima dokumen spesifikasi dalam bentuk url atau hanya json mentah. Proyek ditulis dalam C # dan halamannya adalah https://github.com/Irdis/SwDoc

EDIT

Mungkin ide yang baik untuk memvalidasi spesifikasi json Anda di sini: http://editor.swagger.io/ jika Anda mengalami masalah dengan SwDoc, seperti pdf yang dibuat tidak lengkap.

Lihat https://mrin9.github.io/RapiPdf elemen khusus dengan banyak fitur penyesuaian dan pelokalan.

Penafian: Saya adalah pembuat paket ini

Bagi saya, solusi termudah adalah mengimpor swagger (v2) ke Postman dan kemudian pergi ke tampilan web. Di sana Anda dapat memilih tampilan "kolom tunggal" dan menggunakan browser untuk mencetak ke pdf. Bukan solusi otomatis / terintegrasi tetapi bagus untuk penggunaan tunggal. Ini menangani lebar kertas jauh lebih baik daripada mencetak dari editor2.swagger.io, di mana scrollbar menyebabkan sebagian konten disembunyikan.