Swagger（絲襪哥）他妹JapiDocs自動生成接口文檔，真香

1. 話不多說，有圖有真相，看看香不。

自動本地靜態資源：

 

頁面效果

 

通過Markdown和pandoc生成Word文檔

2. 直接看代碼

2.1 依賴

    <dependency>
      <groupId>io.github.yedaxia</groupId>
      <artifactId>japidocs</artifactId>
      <version>1.4</version>
    </dependency>

2.2 沒有配置，就一個main函數，隨便寫在項目那裏

package com.yarm.config;

import io.github.yedaxia.apidocs.Docs;
import io.github.yedaxia.apidocs.DocsConfig;

public class CreateJapiDocsConfig {
    public static void main(String[] args) {
        DocsConfig config = new DocsConfig();
        // 項目根目錄
        config.setProjectPath("D:\\develop\\code\\java\\my_default\\java-share-base\\japi-docs");
        // 項目名稱
        config.setProjectName("Springboot JapiDocs Demo");
        // 聲明該API的版本
        config.setApiVersion("V1.0");
        // 生成API 文檔所在目錄
        config.setDocsPath("D:\\document\\japi_docs_demo");
        // 配置自動生成
        config.setAutoGenerate(Boolean.TRUE);
        // 執行生成文檔
        Docs.buildHtmlDocs(config);
    }
}

其中，兩個指定的路徑注意一下即可，自己細品

2.3 簡單解釋一下用法

JApiDocs是通過解析Java源碼來實現的，要使得JApiDocs正確工作，需要你在項目中的Controller書寫遵循一定的編碼規範。

如：

    /**
     * 刪除用戶
     * @param userId 用戶ID
     */

其中，註釋，會默認顯示在文檔中，@param表示對參數的解釋，主要是入參的解釋

2.4 寫一個controller

2.4.1 定義統一的返回結果類

package com.yarm.pojo;

import lombok.Data;

@Data
public class Result<T> {
    private int code;
    private boolean status;
    private String msg;
    private T data;
}

這個不解釋，自己細品

2.4.2 DemoController

定義的兩個對象

User類

package com.yarm.pojo;

import lombok.Data;

@Data
public class User {
    /**
     * 用戶Id
    */
    private Long uid;
    /**
     * 用戶名
     */
    private String name;
}

UserVo類

package com.yarm.pojo;

import lombok.Data;

@Data
public class UserVo extends User {
    /**
     * 用戶信息
     */
    private String info;
}

DemoController類

package com.yarm.controller;

import com.yarm.pojo.Result;
import com.yarm.pojo.User;
import com.yarm.pojo.UserVo;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("demo/user")
public class DemoController {
    /**
     * 新增用戶
     * @param user
     * @Author : yarm.yang
     * @Date : 2020/6/23 9:53
    */
    @PostMapping("add")
    public Result<UserVo> add(@RequestBody User user){
        Result<UserVo> result = new Result<>();
        return result;
    }

    /**
     * 查詢用戶列表
     * @param uid 用戶id
     * @param name 用戶名
     * @Author : yarm.yang
     * @Date : 2020/6/23 9:53
     */
    @GetMapping("query")
    public Result<List<UserVo>> query(Long uid, String name){
        Result<List<UserVo>> result = new Result<>();
        return result;
    }
}

3. 重新執行剛纔的main方法，即可重新生成最新的接口文檔

4. 生成Word

main函數中加

config.addPlugin(new MarkdownDocPlugin());

通過pandoc生成

 pandoc -s docs.md -o docs.docx

結果：

 

生成的Word

pandoc的下載路徑：

https://github.com/jgm/pandoc/releases/tag/2.9.2.1

記得配置pandoc的環境變量：path

文檔路徑：

https://pandoc.org/installing.html

用的爽的話，別忘了點贊哦。

倉庫地址：https://github.com/YeDaxia/JApiDocs

 中文文檔：https://japidocs.agilestudio.cn/#/zh-cn/