สร้าง PDF จากเอกสาร Swagger API

ฉันใช้ Swagger UI เพื่อแสดงบริการเว็บ REST ของฉันและโฮสต์ไว้บนเซิร์ฟเวอร์

อย่างไรก็ตามบริการของ Swagger นี้สามารถเข้าถึงได้บนเซิร์ฟเวอร์เฉพาะเท่านั้น หากฉันต้องการทำงานแบบออฟไลน์มีใครรู้บ้างไหมว่าฉันจะสร้าง PDF แบบคงที่โดยใช้ Swagger UI และทำงานกับมันได้อย่างไร นอกจากนี้ PDF ยังง่ายต่อการแชร์กับผู้ที่ไม่มีสิทธิ์เข้าถึงเซิร์ฟเวอร์

ขอบคุณมาก!

วิธีที่สะดวก: การใช้เบราว์เซอร์การพิมพ์ / ดูตัวอย่าง

1. ซ่อนบานหน้าต่างตัวแก้ไข
2. ตัวอย่างก่อนพิมพ์ (ฉันใช้ firefox คนอื่นก็ใช้ได้)
3. เปลี่ยนการตั้งค่าหน้าและพิมพ์เป็น pdf

ฉันหาวิธีโดยใช้https://github.com/springfox/springfoxและ https://github.com/RobWin/swagger2markup

ใช้ Swagger 2 เพื่อใช้งานเอกสาร

คุณสามารถแก้ไขโครงการ REST ของคุณเพื่อสร้างเอกสารแบบคงที่ที่จำเป็น (html, pdf ฯลฯ ) เมื่อสร้างโครงการ

หากคุณมีโปรเจ็กต์ Java Maven คุณสามารถใช้ข้อมูลโค้ดปอมด้านล่าง ใช้ชุดปลั๊กอินเพื่อสร้าง pdf และเอกสาร html (ของทรัพยากร REST ของโครงการ)

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

โปรดทราบว่าลำดับของการดำเนินการมีความสำคัญเนื่องจากเอาต์พุตของปลั๊กอินหนึ่งจะกลายเป็นอินพุตถัดไป:

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

ปลั๊กอิน asciidoctor จะถือว่ามีไฟล์. adoc ที่จะทำงานได้ คุณสามารถสร้างสิ่งที่รวบรวมสิ่งที่สร้างโดยปลั๊กอิน swagger2markup:

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

หากคุณต้องการให้เอกสาร html ที่คุณสร้างขึ้นกลายเป็นส่วนหนึ่งของไฟล์ war ของคุณคุณต้องแน่ใจว่าเอกสารนั้นอยู่ในระดับบนสุด - ไฟล์คงที่ในโฟลเดอร์ WEB-INF จะไม่ถูกเสิร์ฟ คุณสามารถทำได้ในปลั๊กอิน 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>

ปลั๊กอิน war ทำงานบนเอกสารที่สร้างขึ้นดังนั้นคุณต้องตรวจสอบให้แน่ใจว่าปลั๊กอินเหล่านั้นได้รับการดำเนินการในช่วงก่อนหน้านี้

ฉันสร้างเว็บไซต์https://www.swdoc.org/ที่ระบุปัญหาโดยเฉพาะ ดังนั้นจึงทำการswagger.json -> Asciidoc, Asciidoc -> pdfเปลี่ยนแปลงโดยอัตโนมัติตามที่แนะนำในคำตอบ ข้อดีคือคุณไม่จำเป็นต้องทำตามขั้นตอนการติดตั้ง ยอมรับเอกสารข้อมูลจำเพาะในรูปแบบของ url หรือเพียงแค่ json ดิบ โครงการเขียนด้วยภาษา C # และหน้าของมันคือhttps://github.com/Irdis/SwDoc

แก้ไข

อาจเป็นความคิดที่ดีที่จะตรวจสอบข้อกำหนด json ของคุณที่นี่: http://editor.swagger.io/หากคุณมีปัญหากับ SwDoc เช่นไฟล์ PDF ที่สร้างขึ้นไม่สมบูรณ์

ชำระเงินhttps://mrin9.github.io/RapiPdfองค์ประกอบที่กำหนดเองพร้อมคุณสมบัติการปรับแต่งและการแปลมากมาย

คำเตือน: ฉันเป็นผู้เขียนแพ็คเกจนี้

สำหรับฉันวิธีแก้ปัญหาที่ง่ายที่สุดคือการนำเข้า swagger (v2) ไปยัง Postman จากนั้นไปที่มุมมองเว็บ คุณสามารถเลือกมุมมอง "คอลัมน์เดียว" และใช้เบราว์เซอร์เพื่อพิมพ์เป็น pdf ไม่ใช่โซลูชันอัตโนมัติ / รวม แต่เหมาะสำหรับการใช้งานครั้งเดียว มันจัดการกับความกว้างของกระดาษได้ดีกว่าการพิมพ์จาก editor2.swagger.io โดยที่แถบเลื่อนทำให้บางส่วนของเนื้อหาถูกซ่อน