最近のJava API仕様書生成について

この記事はブログに投稿されたものの転載です。

---

最近のJava API仕様書生成という見地からまとめてみました。

なんでAPI仕様書なのか？

オブジェクト指向にはカプセル化という概念があり、クラスメソッドを呼んでやれば期待する値が返ってくる構造になっています。ただし、引数として何を渡せば良いのか、どのような値が返ってくるのか、異常時にどの様な例外処理が発生するのか等々を事前に把握しておかないと、場当たり的にコードを書き散らすことになります。そこで、きちんとAPIを定義しておき、利用者が無駄なく安心してクラスメソッドを利用できるようにしておくワケです。そのためAPI仕様書が必要なのです。

JavaDocの利用

ここからは現在プロジェクトで利用しているAPI仕様書の生成手順について説明しましょう。

まずは皆さんご存知のJavaDocです。JavaDocフォーマットのコメント元にAPI仕様書を生成します。プロジェクトではからMavenを利用しているため、mvnコマンドから生成するようにしています。

pom.xmlより一部抜粋

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <configuration>
                <defaultVersion>${project.version}</defaultVersion>
                <sourcepath>target/generated-sources/delombok</sourcepath>
            </configuration>
        </plugin>
    </plugins>
</build>

API仕様書生成のmvnコマンドは以下の通り。

$ mvn javadoc:javadoc

処理終了後にtarget\site\apidocsへHTMLファイル群が生成されます。sourcepathにてソースコード場所をしている理由については次の文章をご覧ください。

Lombokへの対応

プロジェクトではBeanやDI等の定型記述の簡略化のためにLombokを利用しています。コンパイル時にLombok記述をJavaコードへ変換してくれるため、ビルド先のアプリケーションサーバへLombokライブラリを持っていく手間がかかりません。Javaの開発では必須とも言えるツールです。

ただし、JavaDocで仕様書を生成する場合には、Lombok記述はAPI仕様書の対象とはなりません。そこで、一旦Lombok記述からJavaコードへ変換する処理が必要になります（これを公式ではdelombokと呼ぶ）。そのdelombok済みソースコードをJavaDocのソースコード場所と指定することで漏れのない正確なAPI仕様書が生成できます。mvnコマンドでコンパイルすれば自動的にdelombokしてくれます。

pom.xmlより一部抜粋

<dependencies>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <scope>provided</scope>
    </dependency>
</dependencies>


<build>
    <plugins>
        <plugin>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok-maven-plugin</artifactId>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>delombok</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <addOutputDirectory>false</addOutputDirectory>
                <sourceDirectory>src/main/java</sourceDirectory>
            </configuration>
        </plugin>
    </plugins>
</build>

delombok実行のmvnコマンドは以下の通り。

$ mvn compile

コンパイル終了後にtarget/generate-sources/delombokへdelombok済みソースコードが生成されます。

Swaggerの利用

昨今のWEBアプリケーションでは非同期通信によるサーバサイド処理がメジャーになりました。当然ながらREST APIを設ける場合も多くなり、このような状況から考えてもREST API仕様書を作成しておく方が望ましいです。現在プロジェクトではSwaggerを取り入れています。SwaggaerはAmazon API GatewayやAzure API Managementで採用されているため、ほぼデファクトスタンダードへ成りつつあります。現時点でSwaggerを採用することは無難な手でしょう。有志により公開されたMavenのSwaggerプラグインを用いてREST API仕様書を生成します。

pom.xmlより一部抜粋

<dependencies>
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <scope>provided</scope>
    </dependency>
</dependencies>


<build>
    <plugins>
        <plugin>
            <groupId>com.github.kongchen</groupId>
            <artifactId>swagger-maven-plugin</artifactId>
            <configuration>
                <apiSources>
                    <apiSource>
                        <springmvc>false</springmvc>
                        <locations>com.shdsd.plugin.label.printer.rest</locations>
                        <info>
                            <title>${project.name} API</title>
                            <version>${project.version}</version>
                        </info>
                        <templatePath>${project.basedir}/src/test/resources/strapdown.html.hbs</templatePath>
                        <outputPath>${project.basedir}/target/generated/document.html</outputPath>
                        <swaggerDirectory>${project.basedir}/target/swagger-ui</swaggerDirectory>
                    </apiSource>
                </apiSources>
            </configuration>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

delombok実行のmvnコマンドは以下の通り。

$ mvn compile

コンパイル終了後にtarget/generated/document.htmlが生成されます。templatePathへ配置するファイル群はapi-doc-template/v3.0から取得してください。

最後に

IT技術の流行り廃れが激しいので、ここに記載した内容もしばらく経ったら更新されるかもしれません。