SwaggerAPIドキュメントからPDFを生成する

SwaggerUIを使用してRESTWebサービスを表示し、サーバーでホストしました。

ただし、Swaggerのこのサービスには、特定のサーバーでのみアクセスできます。オフラインで作業したい場合、Swagger UIを使用して静的PDFを作成し、それを操作する方法を知っている人はいますか？さらに、PDFは、サーバーにアクセスできない人と簡単に共有できます。

どうもありがとう！

便利な方法：ブラウザの印刷/プレビューの使用

1. エディタペインを非表示
2. 印刷プレビュー（私はfirefoxを使用しましたが、他の人も問題ありません）
3. ページ設定を変更し、PDFに印刷します

https://github.com/springfox/springfoxと https://github.com/RobWin/swagger2markupを使用して方法を見つけました

Swagger2を使用してドキュメントを実装しました。

プロジェクトのビルド時に必要な静的ドキュメント（html、pdfなど）を生成するように、RESTプロジェクトを変更できます。

Java Mavenプロジェクトがある場合は、以下のpomスニペットを使用できます。一連のプラグインを使用して、（プロジェクトのRESTリソースの）pdfおよびhtmlドキュメントを生成します。

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で実行できます。

<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プラグインは、生成されたドキュメントで機能します。そのため、これらのプラグインが以前のフェーズで実行されていることを確認する必要があります。

特に問題に対処するWebサイトhttps://www.swdoc.org/を作成しました。したがってswagger.json -> Asciidoc, Asciidoc -> pdf、回答で提案されているように、変換を自動化します。これの利点は、インストール手順を実行する必要がないことです。URLまたは生のjsonの形式の仕様ドキュメントを受け入れます。プロジェクトはC＃で記述されており、そのページはhttps://github.com/Irdis/SwDocです。

編集

PDFが不完全に生成されるなど、SwDocに問題がある場合は、ここでjson仕様を検証することをお勧めします：http：//editor.swagger.io/。

https://mrin9.github.io/RapiPdfをチェックアウトして、カスタマイズとローカリゼーション機能が豊富なカスタム要素を確認してください。

免責事項：私はこのパッケージの作者です

私にとって最も簡単な解決策は、Swagger（v2）をPostmanにインポートしてから、Webビューに移動することでした。そこで、「単一列」ビューを選択し、ブラウザを使用してPDFに印刷できます。自動化/統合ソリューションではありませんが、シングルユースに適しています。スクロールバーによってコンテンツの一部が非表示になるeditor2.swagger.ioからの印刷よりも、用紙幅の処理がはるかに優れています。