Java注釋規范(配合EasyYapi使用)

使用范例

類注釋

示例

/**
 * 分類名稱
 * 分類備注/描述
 * @module 歸屬項目
 * @author Allen
 * @date 2020/6/5 下午2:25
 * @copyright 2020 barm Inc. All rights reserved
 */
@RestController
@RequestMapping("/barm")
public class DemoController {

• 第一行默認是 接口 分類名稱
• 第一行到第一個以@開頭的行之前的為 接口描述
• 請注意規范, 類請明確 @author, @date, @copyright
• @module用於分類api , 詳情見下文

通過 live templates 配置類注釋模板

/**
 * TODO
 * TODO
 * @module TODO
 * @author Allen
 * @date $date$ $time$
 * @copyright 2020 barm Inc. All rights reserved
 */

進入 live templates > 新增group > 添加模板cheader

IDEA 配置

• file and code template
• live template

方法注釋

示例

    /**
     * api名稱
     * api描述
     * @param paramA 參數 A
     * @param paramB 參數 B
     * @return {@link ResultVO}
     */
    @PostMapping("/pathOfApi1")
    public ResultVO methodName1(String paramA, String paramB){
        log.info("paramA {} , paramB {} ", paramA, paramB);
        ResultVO resultVO = new ResultVO();
        resultVO.setCode(000);
        resultVO.setMessage("success");
        return resultVO;
    }

• 第一行默認 api名稱
• 第二行默認 api描述
• 入參名后+ 后表示 參數的描述
• @RequestMapping 請明確請求的類型 GET, POST …

   /**
     * yapi接口2
     * 默認使用`application/x-www-form-urlencoded`,
     * 對於`@RequestBody`將使用`application/json`
     * 用注釋`@deprecated`來表示api廢棄
     *
     * @deprecated 改用 {@link DemoController#methodName3(MockDtoOrVo)}
     */
    @Deprecated
    @PostMapping(value = "/pathOfApi2")
    public ResultVO methodName2(@RequestBody MockDtoOrVo jsonModel){
        ResultVO resultVO = new ResultVO();
        resultVO.setCode(000);
        resultVO.setMessage("success");
        return resultVO;
    }

• 默認使用application/x-www-form-urlencoded
• 對於@RequestBody將使用application/json
• 注釋@deprecated來表示api廢棄

不確定的返回類型

/**
  * @result {@link Result}
  * @result {@link Result<UserInfo>}
  */
 public Result mockString() {
     ...
 }

IDEA 配置

直接在 方法前輸入 /** 按 Enter 鍵出

參數注釋

/**
 * 字段注釋
 */
private Long field1;

注釋@deprecated來表示api廢棄

/**
 * 用注釋`@deprecated`來表示字段被廢棄
 * @deprecated It's a secret
 */
private int field5;

使用@NotBlank/@NotNull表示字段必須

/**
 * 如果使用javax.validation的話
 * 可以使用@NotBlank/@NotNull表示字段必須
 */
@NotBlank
@NotNull
private String field6;

字段可能有不同類型的值

/**
  * @maybe {@link UserInfo}
  * @maybe {@link java.lang.String}
  */
 public Object target;

@see 的使用

/**
 * 使用@see來說明當前字段的取值是某個Constant
 * @see DemoConstant#desc
 */
private int field3;

/**
 * 當目標枚舉字段與當前字段名不一致,額外指定
 * @see DemoEnum#getCode()
 */
private int field4;

---

@link 指定類型關聯具體類

• 使用前使用 " " 與其他字句區分開

/**
  * @result {@link Result}
  */
 public Result mockString() {
     ...
 }

@module API 到 指定項目

module用於分類api

• 導出postman時 , 每個module將作為一個單獨的文件夾
• 導出yapi時 , 每個module需要配置相應的token, 即對應一個yapi中的項目
• 默認情況下取當前模塊名(單模塊項目取項目名)

@ignore 忽略API

當在接口注釋使用 @ignore時候 導出被忽略

 /**
     * @ignore
     * @param param
     * @return
     */
    @PostMapping(value = "/pathOfApi4")
    public ResultVO methodName4(@RequestParam String param){
        log.info("param {}", param);
        ResultVO resultVO = new ResultVO();
        resultVO.setCode(000);
        resultVO.setMessage("success");
        return resultVO;
    }

寫在最后

還是老三樣. 歡迎 點贊, 轉發, 評論 ~