Hasilkan PDF dari dokumentasi API Swagger

93

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!

pdf  swagger-ui 
— Aman Mohammed
sumber

Jawaban:

39

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

masukkan deskripsi gambar di sini

— Osify
sumber
Sederhana! Dokumentasinya keluar dengan cukup baik.
— ShaTin
1
Anda bahkan dapat memilih di antara dua desain dokumentasi selama ada dua layanan Swagger: editor.swagger.io (baru) dan editor2.swagger.io (sebelumnya)!
— naXa
UI HTML yang efektif tetapi lossy bcos swagger memiliki banyak tab, untuk parameter metode POST / PUT Anda harus memilih antara tab model dan tab nilai contoh, lalu dalam versi cetak-ke-PDF salah satunya tersembunyi selamanya :(
— chrisinmtown
Ini tidak berhasil untuk saya. Setiap titik akhir akan terpotong dengan akhir halaman (tidak peduli pengaturan halaman apa yang saya gunakan). Halaman berikutnya kemudian akan dimulai di bagian atas blok Endpoint berikutnya. Mungkin ada sesuatu yang berubah sejak jawaban ini ditulis.
— killa-byte
Saya masih melihat ini bisa diterapkan, Anda mungkin perlu menyesuaikan margin. Coba dari editor.swagger.io
— Osify
33

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

Menggunakan Swagger 2 untuk mengimplementasikan dokumentasi.

— Aman Mohammed
sumber
hai, saya juga mencoba membuat dokumentasi offline menggunakan swagger. Apakah Anda dapat menghasilkan dokumentasi swagger ??
— Sunil Rk
ya, saya menggunakan proyek contoh dan mengintegrasikan kode webservice saya di dalamnya dan mampu menghasilkan dokumentasi.
— Aman Mohammed
1
Bisakah Anda memberi tahu saya secara singkat, bagaimana saya dapat mengintegrasikan layanan web saya ke contoh-contoh yang telah Anda sebutkan di atas.
— Sunil Rk
Proyek swagger2markup membutuhkan masukan JSON dari REST API. Jika Anda mengunduh proyek gradle itu dan mengubah file swagger.json dengan detail API Anda lalu menjalankan metode JUnit Swagger2MarkupConverterTest: testSwagger2HtmlConversion, itu akan menghasilkan HTML untuk Anda di folder build / docs / generated / asciidocAsString proyek. Jadi dengan kata lain ada 2 hal. 1) Pertama buat format JSON untuk REST API Anda menggunakan Swagger Editor. 2) Menggunakan Format JSON tersebut, Anda dapat menggunakan proyek swagger2markup untuk menghasilkan dokumentasi HTML mandiri dari API
— Aman Mohammed
22

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.

— Hervian
sumber
Hai @Hervian. Jawaban yang bagus. Saya bisa menggunakan anser Anda sejauh ini. Saya memiliki dua kelas dengan nama yang sama tetapi dalam paket yang berbeda. Namun swagger.json berisi definisi hanya untuk salah satunya. Yang lainnya hilang
— edmond
@Hervian Saya mendapat kesalahan sampai saya melakukan hal berikut 1) membuat file src / main / asciidoc / swagger.adoc dengan konten dari atas. 2) menambahkan properti ini ke POM: <phase.generate-documents> proses-class </phase.generate-documentation> <generated.asciidoc.directory> $ {project.build.directory} / api-gen </ generated. asciidoc.directory> Kemudian jalankan "mvn install" dan saya tidak melihat mvn atau kesalahan plugin tetapi hanya file overview.adoc yang memiliki konten; file definitions.adoc dan paths.adoc tetap kosong. Mohon saran.
— chrisinmtown
15

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.

— Irdis
sumber
3
thx, ya itu cukup bagus, saya menggunakannya untuk proyek pekerjaan saya. Saya sedang berpikir untuk menulis beberapa kode untuk mendukung openapi 3.0 di waktu luang saya.
— Irdis
2
Semua kemuliaan bagi penulis alat yang diandalkannya, ofc
— Irdis
@Irdis Saya mencoba menggunakan tautan. Ini memungkinkan dokumen Swagger 2.0 diurai tetapi dokumen yang saya sediakan adalah Open API 3.0 dan tidak dapat menghasilkan dokumen.
— hellowahab
Saya mencoba swagger 3+ - berfungsi dengan baik, ini menunjukkan html mentah untuk komentar ...
— Sasha Bond
Ini adalah alat yang hebat! Jika Anda pernah memiliki masalah seperti yang saya alami (seperti pdf yang dibuat tidak lengkap), tempel json Anda di sini: editor.swagger.io untuk divalidasi secara otomatis, perbaiki masalah dan Anda akan baik untuk kembali ke alat swdoc dan membuatnya dengan benar kali ini.
— Thales Valias
9

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

Penafian: Saya adalah pembuat paket ini

— Mrinmoy
sumber
2
baru saja diuji tetapi saya tidak mendapatkan respons setelah mengklik "Hasilkan PDF" dengan spesifikasi pengujian (petstore)?
— imehl
1
@imehl Ini berfungsi dengan baik ketika saya menguji saya di mac / chrome, mac / firefox, mac / safari dan windows / chrome. Ini hanya berfungsi di browser web yang mendukung komponen web seperti Chrome, Firefox, dan Safari. Jika masih menghadapi masalah, silakan masuk ke Github github.com/mrin9/RapiPdf
— Mrinmoy
@Mrinmoy Saya memiliki masalah yang sama dengan imehl, itu membuka tab baru tetapi segera ditutup (ubuntu 18.04 + firefox / chrome keduanya menghasilkan hasil yang sama). Kemudian saya melakukannya di windows dan itu bekerja seperti pesona. Terima kasih untuk alat ini, luar biasa.
— Dabux
3
@Dabux tidak pernah diuji di ubuntu, tetapi ada satu situasi yang saya tahu di mana orang menghadapi masalah yang sama seperti yang Anda jelaskan, dan itu adalah ketika Anda memiliki pemblokir atau pemblokir popup aktif di browser
— Mrinmoy
@Mrinmoy Anda benar, saya memiliki pemblokir iklan, itu karena itu, bukan karena OS.
— Dabux
1

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.

— Simon
sumber
1
mencoba menggunakan ini tetapi mencetak melalui halaman web menambahkan beberapa tautan dan info lainnya juga.
— hellowahab
Ya, saya seharusnya menyebutkan itu. Tidak masalah untuk saya gunakan.
— Simon
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.