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

投稿日: 2022-10-27 2022-10-27
タグ: OpenAPI, REST, Swagger

1. 概要

このチュートリアルでは、SwaggerAPIドキュメントからPDFファイルを生成するさまざまな方法を理解します。 Swaggerについて理解するには、 Spring RESTAPIを使用したSwagger2のセットアップに関するチュートリアルを参照してください。

2. Mavenプラグインを使用してPDFを生成する

Swagger APIドキュメントからPDFファイルを生成するための最初のソリューションは、一連のMavenプラグインに基づいています。このアプローチでは、Javaプロジェクトのビルド時にPDFファイルを取得します。

目的のPDFファイルを作成する手順には、Mavenビルド中に特定の順序で複数のプラグインを適用することが含まれます。プラグインは、リソースを選択し、前のフェーズからの出力を次のフェーズの入力として伝播するように構成する必要があります。それでは、それぞれがどのように機能するかを見てみましょう。

2.1. swagger-maven-pluginプラグイン

最初に使用するプラグインはswagger-maven-pluginです。このプラグインは、RESTAPIのswagger.jsonファイルを生成します。

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.3</version>
    <configuration>
        <apiSources>
	    <apiSource>
        	<springmvc>false</springmvc>
		<locations>com.baeldung.swagger2pdf.controller.UserController</locations>
		<basePath>/api</basePath>
		<info>
	            <title>DEMO REST API</title>
		    <description>A simple DEMO project for REST API documentation</description>
		    <version>v1</version>
		</info>
		<swaggerDirectory>${project.build.directory}/api</swaggerDirectory>
	        <attachSwaggerArtifact>true</attachSwaggerArtifact>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
		<goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

APIの場所を指定し、プラグインがswagger.jsonファイルを生成するビルドプロセスのフェーズを定義する必要があります。ここでは、execution タグで、packageフェーズ中にこれを実行するように指定しています。

2.2. swagger2markup-maven-pluginプラグイン

必要な2番目のプラグインは、swagger2markup-maven-pluginです。 は、前のプラグインのswagger.json出力を入力として受け取り、 Asciidocを生成します。

<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>
        <markupLanguage>asciidoc</markupLanguage>
    </configuration>
    <executions>
        <execution>
	    <phase>package</phase>
            <goals>
                <goal>process-swagger</goal>
            </goals>
        </execution>
    </executions>
</plugin>

ここでは、inputDirectoryタグとoutputDirectoryタグを指定します。ここでも、 package を、RESTAPIのAsciidocを生成するためのビルドフェーズとして定義します。

2.3. asciidoctor-maven-pluginプラグイン

使用する3番目の最後のプラグインはasciidoctor-maven-pluginです。 3つのプラグインの最後として、このプラグインはAsciidocからPDFファイルを生成します。

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.2.1</version>
    <dependencies>
        <dependency>
	    <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.6.0</version>
        </dependency>
    </dependencies>
    <configuration>
        <sourceDirectory>${project.build.outputDirectory}/../asciidoc</sourceDirectory>
        <sourceDocumentName>overview.adoc</sourceDocumentName>
        <attributes>
            <doctype>book</doctype>
            <toc>left</toc>
            <toclevels>2</toclevels>
            <generated>${generated.asciidoc.directory}</generated>
        </attributes>
    </configuration>
    <executions>
        <execution>
            <id>asciidoc-to-pdf</id>
            <phase>package</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <backend>pdf</backend>
                <outputDirectory>${project.build.outputDirectory}/api/pdf</outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

基本的に、前のフェーズでAsciidocが生成された場所を提供します。次に、PDFドキュメントを生成する場所を定義し、PDFを生成するフェーズを指定します。ここでも、パッケージフェーズを使用しています。

3. SwDocを使用してPDFを生成する

Swagger to PDFは、 swdoc.org で入手可能なオンラインツールであり、提供されているswagger.json仕様を使用してPDFファイルでAPIドキュメントを生成します。 Swagger2MarkupコンバーターとAsciiDoctor。に依存しています。

原則は、前のソリューションの原則と同様です。まず、Swagger2Markupはswagger.jsonをAsciiDocファイルに変換します。次に、Asciidoctorはそれらのファイルをドキュメントモデルに解析し、PDFファイルに変換します。

このソリューションは使いやすく、Swagger2APIドキュメントがすでにある場合はに適しています。

PDFは次の2つの方法で生成できます。

swagger.jsonファイルへのURLを提供する
swagger.jsonファイルの内容をツールのテキストボックスに貼り付けます

Swaggerで公開されているのPetStoreAPIドキュメントを使用します。

この目的のために、JSONファイルをコピーしてテキストボックスに貼り付けます。

次に、[生成]ボタンをクリックすると、PDF形式のドキュメントが表示されます。

4. 結論

この短いチュートリアルでは、SwaggerAPIドキュメントからPDFを生成する2つの方法について説明しました。

最初のアプローチは、Mavenプラグインに依存しています。 3つのプラグインを使用して、アプリケーションの構築中にRESTAPIドキュメントを生成できます。

2番目のソリューションでは、SwDocオンラインツールを使用してPDFドキュメントを生成する方法について説明します。 swagger.json へのリンクからドキュメントを生成するか、JSONファイルの内容をツールに貼り付けることができます。

いつものように、これらの例のコードはGitHubでから入手できます。

getdocs

13036