[api document] JApiDocsを使って、spring bootのapi documentの自動作成

概要

JApiDocsとはアノテーションを書かなくても、apiのドキュメントを自動生成できるライブラリーだそうです。便利かなと思い、使ってみました。

A magical api documentation generator without annotation for springboot.

requirement

• Supported JDK：1.8+
• maven・gradle(今回は Gradle 6.8.3を使います)
• spring-boot cli(Spring CLI v2.4.4)

OS

macOS

手順

spring-boot cliを使い、spring bootのプロジェクトを作成

spring init --build=gradle --java-version=1.8 --dependencies=web japidoc

上記のコマンドを実行し終わると下記のようなディレクトリは作成されました。

├── HELP.md
├── build.gradle
├── gradlew
├── gradlew.bat
├── settings.gradle
├── src
│   ├── main
│   │   ├── java
            |- com.example.japidoc
               |- DemoApplication.java

JApiDocsの依頼を追加

build.graldeにJApiDocsを追加

// build.gradle
dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-web'
  testImplementation 'org.springframework.boot:spring-boot-starter-test'
  // japidocs追加
  implementation 'io.github.yedaxia:japidocs:1.4.4'
}

JApiDocsを設定する

main()メソッドに下記のコードを追加

public class DemoApplication {
	final static String version = "v1.0";
	public static void main(String[] args) {
		SpringApplication.run(DemoApplication.class, args);
// JApiDocの設定を追加する
		DocsConfig config = new DocsConfig();
		String userDirectory = System.getProperty("user.dir");
// 項目のrootパスを設定する
		config.setProjectPath(userDirectory);
// 項目名設定		config.setProjectName(Paths.get(userDirectory).getFileName().toString());
// 項目バージョンを設定する
		config.setApiVersion(version);
// apiドキュメントの出力ディレクトリを設定する
		config.setDocsPath(userDirectory);
// 自動出力
		config.setAutoGenerate(Boolean.TRUE);
// markdownファイルプラグインを追加してあげれば、markdownファイルの出力も可能となる
// htmlファイルを出力
		config.addPlugin(new MarkdownDocPlugin());
		Docs.buildHtmlDocs(config);
	}

}

controllerを書いてみる

下記のcontrollerを追加し、apiのドキュメントを作成してみる

/**
 * User API
 * @description this is a class
 */
@RestController
public class HelloWorld {

    /**
     * hello world
     * @description this is a method
     * @param msg
     */
    @RequestMapping(path = "list", method = {RequestMethod.GET})
    public String home(@RequestParam String msg) {
        return "Hello World!";
    }

    @ApiDoc(stringResult = "{code: 0, data: 'success'}")
    @GetMapping(value = "custom-json")
    public String customJsonResult(){ return "ok"; }
}

ドキュメントは出力された

v1.0
├── apidoc.log
├── com_example_japidoc_HelloWorld.html
├── com_example_japidoc_controller_HelloWorld.html

├── index.html
├── japidoc-v1.0-api-docs.md
└── style.css

index.htmlを開くみると下記の感じです。

もっと細かい設定はここ参考します。

感想

swaggerはpost、curlコマンドなども用意してくれて、便利ですが、markdownファイルの出力なら、ちょっと面倒気がしまして、JApiDocsと併用する形なら、さらに便利になるかもしれません。