通过使用JApiDocs工具，自动创建Spring Boot API文档

2 年 ago
清, 扬
2 minutes

简要概述

据说JApiDocs是一个可以自动生成API文档而无需编写注释的库。我觉得挺方便的，所以就试用了一下。

一个神奇的Spring Boot API文档生成器，无需注释。

要求

    • Supported JDK：1.8+

 

    • maven・gradle(今回は Gradle 6.8.3を使います)

 

    spring-boot cli(Spring CLI v2.4.4)

操作系统

苹果操作系统中的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.gradle中添加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);
    }

}

我试着写一个控制器 (wǒ xiě

添加以下控制器并创建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时，看起来如下所示。

スクリーンショット 2021-04-01 15.17.57.png

我会在这里参考更详细的设置。

印象

Swagger提供了post、curl等命令，非常方便。但是，如果要输出markdown文件可能会有些麻烦，如果可以与JApiDocs一起使用，可能会变得更加方便。

bannerAds