對Swagger相當不爽的兩點，一是要大量寫各種註解，二是很被詬病的一點，對返回物件的描述相當不人性化（雖然可以寫程式碼來實現，但不爽）。

在大部分時候，我們其實只關注介面的4個方面： 介面功能描述、介面URL、提交引數說明、返回結果說明。
JApiDocs完美的滿足上面的基本要求，見下圖：

介面文件生成器——JApiDocs，JApiDocs官網教程相當棒：https://japidocs.agilestudio.cn/#/zh-cn/

下面的步驟是大量照搬JApiDocs官網的內容。

第一步：新增依賴

通過IDEA建立Spring Boot，在建立工程時，可以把web依賴勾選上（不勾選也沒關係，後面在pom.xml中再新增也行）。

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

第二步：配置引數

在任意一個main入口執行下面的程式碼，我是直接寫在Spring Boot的啟動類中的，如下：

package com.jcj.japidemo;
import io.github.yedaxia.apidocs.Docs;
import io.github.yedaxia.apidocs.DocsConfig;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class JapidemoApplication
{
    public static void main(String[] args)
    {
        SpringApplication.run(JapidemoApplication.class, args);

        //JApiDocs 配置引數
        DocsConfig config = new DocsConfig();
        config.setProjectPath("C:\\IdeaProjects\\japidemo"); // 專案根目錄
        config.setProjectName("japidemo"); // 專案名稱
        config.setApiVersion("V1.0");       // 宣告該API的版本
        config.setDocsPath("C:\\IdeaProjects\\japidemo\\apidoc"); // 生成API 文件所在目錄
        config.setAutoGenerate(Boolean.TRUE);  // 配置自動生成
        Docs.buildHtmlDocs(config); // 執行生成文件
    }
}
 

所有的工作就做完了！相當Easy

在編碼時，你只需注意編碼規範，，順手寫好必要的註釋就行了，那麼介面文件就能自動生成，不用加任何註解。

1. 類上加註釋（不是註解）

“使用者介面”註釋會顯示為左側樹形目錄的根目錄

/**
 * 使用者介面
 * @Auther: 江成軍
 * @Date: 2021/8/22 22:16
 */
@RestController
@RequestMapping(value="/apiuser")
public class UserController
{
	...
}

2. 方法上加註釋（不是註解）

"使用者介面"會顯示為左側導航樹的目錄，@description會顯示為副標題，每一個引數對應一個@param

/**
    * 使用者詳情(RESTFul方式)
    * @description 根據姓名，年齡查詢使用者詳情，url中只需傳值
    * @param name 姓名
    * @param age 年齡
    * @Author 江成軍
    * @Date 2021/8/22 23:32
    **/
    @GetMapping(value="/users/{name}/{age}")
    public Result<User> userDetail2(@PathVariable String name, @PathVariable int age)
    {
        System.out.println(name+","+age);

        Result result=new Result();
        User u1=new User();
        u1.setName("張三");
        u1.setAge(23);
        u1.setWeight(122.6f);

        result.setCode(200);
        result.setMessage("更新成功");
        result.setData(u1);

        return result;
    }

生成的介面描述顯示見下圖:

3. 實體類上加註釋（不是註解）

直接在屬性上面加註釋就行了，用//或者*註釋都行，我比較喜歡用//，見下圖：


這樣在返回結果上面，直接就會清楚明瞭的顯示:

WEB專案開發中碰到的問題千奇百怪，大家想了解對如何快速的掌握Spring Boot，可以參見視訊：

51CTO：Spring Boot+Bootstrap開發小而完整web專案
騰訊課堂：Spring Boot+Bootstrap開發小而完整web專案
CSDN學院：Spring Boot+Bootstrap開發小而完整web專案
網易雲課堂：Spring Boot+Bootstrap開發小而完整web專案